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

A picture drawn in the entity's rectangle: the texture to show, a fallback texture, and whether loading succeeded. More...

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

Inheritance diagram for guillaume::components::Image:
Collaboration diagram for guillaume::components::Image:

Public Types

enum class  LoadState { Pending , Loaded , Failed }
 Whether the texture could be loaded, as recorded by systems::ImageRender. More...

Public Member Functions

 Image (void)=default
 Default constructor for the Image component.
 ~Image (void)=default
 Default destructor for the Image component.
Image & setTexturePath (const std::string &path)
 Choose the texture to draw.
const std::string & getTexturePath (void) const
 Get the path of the texture to draw.
Image & setFallbackPath (const std::string &path)
 Set the texture drawn when the main texture fails to load.
const std::string & getFallbackPath (void) const
 Get the path of the fallback texture.
LoadState getLoadState (void) const
 Get the outcome of the last load attempt.
Image & setLoadState (LoadState state, bool usingFallback=false)
 Record the outcome of a load attempt. Called by systems::ImageRender.
bool isUsingFallback (void) const
 Check whether the fallback texture is drawn.
Public Member Functions inherited from guillaume::ecs::Component
bool hasChanged (void) const
 Tell whether a value of the component changed since the flags were last reset (the end of the previous frame).
void setHasChanged (bool hasChanged)
 Raise or lower the changed flag.
 Component (void)=default
 Create a component that is not marked as changed.
virtual ~Component (void)=default
 Virtual destructor, so components can be destroyed through the base class.

Detailed Description

A picture drawn in the entity's rectangle: the texture to show, a fallback texture, and whether loading succeeded.

entities::Image (or the application) writes the two paths. systems::ImageRender (Render phase) loads the texture through the resource provider, draws it stretched over the entity's components::Bound at its components::Transform, and records the outcome with setLoadState().

registry.getComponent<components::Image>(id)
.setTexturePath("images/avatar.png")
.setFallbackPath("images/placeholder.png");
A picture drawn in the entity's rectangle: the texture to show, a fallback texture,...
Definition image.hpp:56
Image & setTexturePath(const std::string &path)
Choose the texture to draw.
Definition image.cpp:27
Image & setFallbackPath(const std::string &path)
Set the texture drawn when the main texture fails to load.
Definition image.cpp:39
Note
The image has no size of its own: set the Bound, or the image is drawn with a size of zero. The aspect ratio of the texture is not preserved.
The load state belongs to systems::ImageRender, which rewrites it every frame. Read it; do not set it.
See also
systems::ImageRender, entities::Image, components::Bound

Definition at line 55 of file image.hpp.

Member Enumeration Documentation

◆ LoadState

Whether the texture could be loaded, as recorded by systems::ImageRender.

Enumerator
Pending 

Not attempted since the path was set.

Loaded 

The texture (or the fallback) is drawn.

Failed 

Neither loaded; nothing is drawn.

Definition at line 62 of file image.hpp.

Member Function Documentation

◆ getFallbackPath()

const std::string & guillaume::components::Image::getFallbackPath ( void ) const

Get the path of the fallback texture.

Returns
The path; empty (the default) when there is no fallback.

Definition at line 52 of file image.cpp.

◆ getLoadState()

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

Get the outcome of the last load attempt.

Returns
Pending until systems::ImageRender has processed the entity, then Loaded or Failed.

Definition at line 57 of file image.cpp.

◆ getTexturePath()

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

Get the path of the texture to draw.

Returns
The path given to setTexturePath(); empty by default.

Definition at line 76 of file image.cpp.

◆ isUsingFallback()

bool guillaume::components::Image::isUsingFallback ( void ) const

Check whether the fallback texture is drawn.

Returns
True when the main texture failed to load and the fallback is drawn in its place.

Definition at line 71 of file image.cpp.

◆ setFallbackPath()

Image & guillaume::components::Image::setFallbackPath ( const std::string & path)

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

When the path differs from the stored one, a Failed load state goes back to Pending and the component is marked changed.

Parameters
pathThe path of the fallback texture; empty for no fallback.
Returns
This component, for chaining.

Definition at line 39 of file image.cpp.

Here is the call graph for this function:

◆ setLoadState()

Image & guillaume::components::Image::setLoadState ( LoadState state,
bool usingFallback = false )

Record the outcome of a load attempt. Called by systems::ImageRender.

Unlike the other setters it never marks the component changed: the render system calls it every frame, and flagging a change there would keep the entity dirty for ever.

Parameters
stateThe outcome of the attempt.
usingFallbackTrue when the fallback texture is the one drawn.
Returns
This component, for chaining.

Definition at line 62 of file image.cpp.

Here is the call graph for this function:

◆ setTexturePath()

Image & guillaume::components::Image::setTexturePath ( const std::string & path)

Choose the texture to draw.

When the path differs from the stored one, the load state goes back to Pending, the fallback flag is cleared and the component is marked changed. The same path does nothing.

Parameters
pathThe path of the texture, as understood by the application's resource provider.
Returns
This component, for chaining.

Definition at line 27 of file image.cpp.

Here is the call graph for this function:

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