guillaume 2026.6.1
A C++ UI framework designed for modern desktop and extended reality (XR) applications.
Loading...
Searching...
No Matches
guillaume::entities::Image Class Reference

A picture loaded from a texture file and stretched over a rectangle. More...

#include <headers/guillaume/entities/image.hpp>

Inheritance diagram for guillaume::entities::Image:
Collaboration diagram for guillaume::entities::Image:

Classes

class  Builder
 Configures Image widgets and registers them in the scene's entity registry. More...

Public Member Functions

 ~Image (void)
 Destructor.
Image & setTexturePath (const std::string &texturePath)
 Change the texture to draw.
const std::string & getTexturePath (void) const
 Get the path of the texture the image was asked to draw.
Image & setFallbackPath (const std::string &fallbackPath)
 Set the texture drawn when the main one fails to load.
Image & setSize (float width, float height)
 Set the displayed size, written to components::Bound.
Image & setAspectRatio (float width, float aspectRatio)
 Set the displayed size from a width and an aspect ratio.
components::Image::LoadState getLoadState (void) const
 Tell whether the texture could be loaded.
Image & setAccessibilityLabel (const std::string &label)
 Describe the picture for assistive technologies.
Public Member Functions inherited from guillaume::ecs::EntityFiller< components::Transform, components::Bound, components::Image, components::Accessibility >
 EntityFiller (ComponentRegistry &componentRegistry)
 Create the entity, its listed components and its components::Hierarchy.
virtual ~EntityFiller (void)=default
 Destroy the entity object; its components stay in the registry (see EntityRegistry::removeEntity).
Public Member Functions inherited from guillaume::ecs::Entity
 Entity (void)
 Create an entity with a fresh identifier, an empty signature, no parent and no component.
virtual ~Entity (void)=default
 Destroy the entity object.
Entity::Identifier getIdentifier (void) const noexcept
 Get the identifier of the entity.
Entity::Signature getSignature (void) const noexcept
 Get the set of component types the entity declares.
void setSignature (const Signature &signature)
 Replace the signature of the entity.
std::int32_t getLayer (void) const noexcept
 Get the depth of the entity in the tree.
Entity & setParent (std::shared_ptr< Entity > parent)
 Attach the entity under another one, or detach it.
std::vector< Identifier > releaseComponents (void)
 Drop the entity's place in the tree and all its components.
std::shared_ptr< Entity > getParent (void) const noexcept
 Get the parent entity.

Static Public Member Functions

template<typename... Arguments>
static std::shared_ptr< Image > create (Arguments &&...arguments)
 Build an image without registering it in an entity registry.
Static Public Member Functions inherited from guillaume::ecs::Entity
template<InheritFromComponent... ComponentTypes>
static Signature getSignatureFromTypes (void)
 Build the signature that has exactly the bits of the given component types.

Additional Inherited Members

Public Types inherited from guillaume::ecs::Entity
using Identifier = std::size_t
 The key under which an entity's components are stored. Systems and components refer to entities by this value.
using Signature = std::bitset<128>
 A set of component types, one bit per type (bit position given by ComponentTypeId, MaxComponentTypes bits).
Static Public Attributes inherited from guillaume::ecs::Entity
static constexpr Identifier InvalidIdentifier
 "No entity": never the identifier of a real entity
Protected Member Functions inherited from guillaume::ecs::EntityFiller< components::Transform, components::Bound, components::Image, components::Accessibility >
ComponentRegistry & getComponentRegistry (void)
 Get the registry that stores this entity's components.
Protected Member Functions inherited from guillaume::ecs::Entity
void attachHierarchy (ComponentRegistry &componentRegistry)
 Give the entity a components::Hierarchy in a registry and add that component to its signature.
template<InheritFromComponent... ComponentTypes>
void setSignature (void)
 Replace the signature by the one made of the given component types.

Detailed Description

A picture loaded from a texture file and stretched over a rectangle.

Image is a leaf widget: it has no children. Its state lives in components::Image (texture path, fallback path, loading state), components::Bound (displayed size), components::Transform and components::Accessibility (role Image and label). systems::ImageRender loads the texture and draws it over the Bound each frame, in the Render phase, and records the outcome as the loading state. The class itself holds no field.

Image::Builder builder(getComponentRegistry(), getEntityRegistry());
auto photo = builder.withSize(160.0f, 90.0f)
.withFallbackPath("images/placeholder.png")
.makeImage(parent, "images/photo.png");
photo->setAccessibilityLabel("Team photo");
Configures Image widgets and registers them in the scene's entity registry.
Definition image.hpp:84

Image::create(registry, texturePath) builds the same widget without registering it in an entity registry; set its size and fallback with the setters afterwards.

Watch out:

See also
components::Image, systems::ImageRender, Icon

Definition at line 74 of file image.hpp.

Constructor & Destructor Documentation

◆ ~Image()

guillaume::entities::Image::~Image ( void )

Destructor.

Definition at line 149 of file image.cpp.

Member Function Documentation

◆ create()

template<typename... Arguments>
std::shared_ptr< Image > guillaume::entities::Image::create ( Arguments &&... arguments)
inlinestatic

Build an image without registering it in an entity registry.

The arguments are forwarded to the private constructor: (registry, texturePath). An image has no children to build.

Template Parameters
ArgumentsThe constructor argument types.
Parameters
argumentsThe constructor arguments, as listed above.
Returns
The new image. The caller owns it.

Definition at line 177 of file image.hpp.

Here is the caller graph for this function:

◆ getLoadState()

components::Image::LoadState guillaume::entities::Image::getLoadState ( void ) const

Tell whether the texture could be loaded.

Returns
Pending before systems::ImageRender first ran on the image, Loaded when the texture or its fallback is drawn, Failed when neither could be loaded.

Definition at line 134 of file image.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getTexturePath()

const std::string & guillaume::entities::Image::getTexturePath ( void ) const

Get the path of the texture the image was asked to draw.

Returns
The texture path stored in components::Image. It does not change when the fallback is drawn instead.

Definition at line 98 of file image.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setAccessibilityLabel()

Image & guillaume::entities::Image::setAccessibilityLabel ( const std::string & label)

Describe the picture for assistive technologies.

Parameters
labelThe text announced for the image, written to components::Accessibility. The role is always Image.
Returns
Reference to this image for chaining.

Definition at line 141 of file image.cpp.

Here is the call graph for this function:

◆ setAspectRatio()

Image & guillaume::entities::Image::setAspectRatio ( float width,
float aspectRatio )

Set the displayed size from a width and an aspect ratio.

The height is width / aspectRatio: a width of 160 with a ratio of 16.0f / 9.0f gives a height of 90. The ratio is not stored; it is applied once.

Parameters
widthThe width, in dp. Must be positive.
aspectRatioThe width divided by the height. Must be positive.
Returns
Reference to this image for chaining.
Exceptions
std::invalid_argumentIf an argument is zero or negative.

Definition at line 125 of file image.cpp.

Here is the call graph for this function:

◆ setFallbackPath()

Image & guillaume::entities::Image::setFallbackPath ( const std::string & fallbackPath)

Set the texture drawn when the main one fails to load.

Parameters
fallbackPathThe path of the fallback texture file, or an empty string for no fallback.
Returns
Reference to this image for chaining.

Definition at line 105 of file image.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setSize()

Image & guillaume::entities::Image::setSize ( float width,
float height )

Set the displayed size, written to components::Bound.

Parameters
widthThe width, in dp. Must be positive.
heightThe height, in dp. Must be positive.
Returns
Reference to this image for chaining.
Exceptions
std::invalid_argumentIf a dimension is zero or negative.

Definition at line 113 of file image.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setTexturePath()

Image & guillaume::entities::Image::setTexturePath ( const std::string & texturePath)

Change the texture to draw.

systems::ImageRender loads it at the next Render phase.

Parameters
texturePathThe path of the new texture file, written to components::Image.
Returns
Reference to this image for chaining.

Definition at line 153 of file image.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

The documentation for this class was generated from the following files: