EntropyCanvas::CanvasClient

EntropyCanvas::CanvasClient

CanvasClient - IDataProvider implementation for CanvasEngine connectivity. More…

#include <CanvasClient.h>

Inherits from EntropyCanvas::IDataProvider

Public Classes

	Name
class	UpdateMaterialHandle Handle for tracking material property update operations.
struct	PropertyRegistryEntry Property registration info for mapping hashes back to entity/property metadata.
class	CreateMaterialHandle Handle for tracking material creation operations.
class	BindMeshMaterialsHandle Handle for tracking mesh material binding operations.

Public Types

	Name
using std::function< void(bool success, const std::string &errorMessage)>	SetSceneEnabledCallback Callback for scene enable/disable response.
using std::function< void(uint64_t entityId, const std::vector< AssetId > &materialIds, uint64_t originSessionId)>	MeshMaterialBindingCallback Callback for mesh material binding update events.
using std::function< void(const AssetId &materialId, const MaterialData &material)>	MaterialReceivedCallback Callback for material received events.
using std::function< void(const AssetId &materialId, const std::string &propertyName, const MaterialPropertyValue &value, uint64_t newVersion)>	MaterialPropertyChangedCallback Callback for material property change events.
using std::function< void(uint64_t entityId)>	EntityDestroyedCallback Callback for entity destruction events from server.
using std::function< void(uint64_t entityId, const std::string &appId, const std::string &typeName, uint64_t parentId, const std::vector< EntropyEngine::Networking::NetworkSession::ComponentGroupData > &components, const std::string &entityName)>	EntityCreatedCallback Callback for entity creation events from server.
using std::function< void(bool success, const std::string &errorMessage)>	DestroySceneCallback Callback for scene destruction response.
using std::function< void(bool success, uint64_t sceneId, const std::string &errorMessage)>	CreateSceneCallback Callback for scene creation response.
using std::function< void(bool success, const std::string &errorMessage)>	AddEntityToSceneCallback Callback for add entity to scene response.

Public Functions

	Name
	~CanvasClient() override
std::shared_ptr< UpdateMaterialHandle >	updateMaterialProperty(const AssetId & materialId, const std::string & propertyName, const MaterialPropertyValue & value) Update a single material property.
std::shared_ptr< UpdateMaterialHandle >	updateMaterialProperties(const AssetId & materialId, const std::map< std::string, MaterialPropertyValue > & properties) Update multiple material properties atomically.
void	unsubscribeMaterial(const AssetId & materialId) Unsubscribe from material updates.
TextureClient *	textureClient() Get the texture client for texture operations.
EntropyEngine::Networking::Result< void >	syncWorld(flecs::world & world) Sync all entities in a Flecs world to CanvasEngine.
EntropyEngine::Networking::Result< void >	syncEntity(flecs::entity entity, uint64_t sceneId =0) Sync a Flecs entity to CanvasEngine.
virtual void	subscribeMaterial(const AssetId & materialId) override Subscribe to updates for a material.
ShaderClient *	shaderClient() Get the shader client for shader operations.
void	setupBuiltinSyncObservers(flecs::world & world) Set up reactive sync observers for all built-in components.
virtual void	setUsdSnapshotCallback(UsdSnapshotCallback callback) override Set the callback for receiving raw USD scene data.
void	setSceneEnabled(uint64_t sceneId, bool enabled, SetSceneEnabledCallback callback) Enable or disable a scene.
void	setMeshMaterialBindingCallback(MeshMaterialBindingCallback callback) Set callback for mesh material binding updates from other clients.
void	setMaterialReceivedCallback(MaterialReceivedCallback callback) Set callback for receiving material data.
void	setMaterialPropertyChangedCallback(MaterialPropertyChangedCallback callback) Set callback for material property changes.
void	setEntityDestroyedCallback(EntityDestroyedCallback callback) Set callback for entity destruction events.
void	setEntityCreatedCallback(EntityCreatedCallback callback) Set callback for entity creation events.
virtual void	setDeltaCallback(DeltaCallback callback) override Set the callback for property delta updates.
void	setClientType(const std::string & clientType) Set the client type for handshake identification.
void	setClientId(const std::string & clientId) Set the client ID for handshake identification.
void	setActiveScene(uint64_t sceneId) Set the active scene for entity creation.
virtual void	requestSnapshot(SnapshotCallback callback) override Request a full scene snapshot from the server.
template <typename T > void	registerSyncableComponent(flecs::world & world, const EntropyEngine::Networking::ComponentSchema & schema) Register a custom component type for reactive sync.
void	poll() Poll for network events.
CanvasClient &	operator=(const CanvasClient & ) =delete
bool	isEntitySynced(flecs::entity entity) const Check if an entity has been synced to CanvasEngine.
virtual bool	isConnected() const override Check if connected to the server.
bool	hasSyncObservers() const Check if reactive sync observers are active.
virtual uint32_t	getServerId() const override Get the server ID.
const std::string &	getEndpoint() const Get the current connection endpoint.
std::string	getDefaultEndpoint() Get the default CanvasEngine IPC endpoint for this platform.
uint64_t	getActiveScene() const Get the currently active scene ID.
void	disconnect() Disconnect from the server.
void	destroyScene(uint64_t sceneId, DestroySceneCallback callback) Destroy a scene on the server.
EntropyEngine::Networking::Result< void >	deleteEntity(flecs::entity entity) Mark an entity as deleted on CanvasEngine.
void	createTransientScene(const std::string & sceneName, CreateSceneCallback callback) Create a transient scene on the server.
void	createPersistentScene(const std::string & sceneName, CreateSceneCallback callback) Create a persistent scene on the server.
std::shared_ptr< CreateMaterialHandle >	createMaterial(const MaterialData & material) Create a material on the server.
bool	connectAndWait(const std::string & endpoint ="", std::chrono::milliseconds timeout =std::chrono::seconds(5)) Connect to CanvasEngine and wait for handshake completion.
bool	connect(const std::string & endpoint) Connect to a CanvasEngine server.
std::shared_ptr< BindMeshMaterialsHandle >	bindMeshMaterials(uint64_t entityId, const std::vector< AssetId > & materialIds) Bind materials to a mesh entity.
AssetClient *	assetClient() Get the asset client for asset operations.
void	addEntityToScene(uint64_t entityId, uint64_t sceneId, AddEntityToSceneCallback callback) Add an entity to a scene.
	CanvasClient()
	CanvasClient(const CanvasClientConfig & config)
	CanvasClient(const CanvasClient & ) =delete

Additional inherited members

Public Types inherited from EntropyCanvas::IDataProvider

	Name
using std::function< void(const std::string &usdText)>	UsdSnapshotCallback
using std::function< void(const SceneSnapshot &)>	SnapshotCallback
using std::function< void(const PropertyDelta &)>	DeltaCallback

Public Functions inherited from EntropyCanvas::IDataProvider

	Name
virtual	~IDataProvider() =default

Detailed Description

class EntropyCanvas::CanvasClient;

CanvasClient - IDataProvider implementation for CanvasEngine connectivity.

Connects to a CanvasEngine server and provides scene data through the IDataProvider interface. Handles:

• Connection management (local sockets or remote WebRTC)
• Protocol handshake
• Scene snapshot requests and delta subscriptions
• Message deserialization into SDK types

Usage:

CanvasClient client;
if (client.connect("/tmp/canvasengine.sock")) {
    // Set up callbacks
    client.requestSnapshot([](const SceneSnapshot& snap) { ... });
    client.setDeltaCallback([](const PropertyDelta& delta) { ... });

    // Poll for updates in main loop
    while (running) {
        client.poll();
        // ... render ...
    }
}
client.disconnect();

Public Types Documentation

using SetSceneEnabledCallback

using EntropyCanvas::CanvasClient::SetSceneEnabledCallback = std::function<void(bool success, const std::string& errorMessage)>;

Callback for scene enable/disable response.

using MeshMaterialBindingCallback

using EntropyCanvas::CanvasClient::MeshMaterialBindingCallback =
std::function<void(uint64_t entityId, const std::vector<AssetId>& materialIds, uint64_t originSessionId)>;

Callback for mesh material binding update events.

Parameters:

• entityId Entity whose materials were changed
• materialIds New list of material AssetIds per submesh
• originSessionId Session that made the change

Called when another client changes materials bound to a mesh.

using MaterialReceivedCallback

using EntropyCanvas::CanvasClient::MaterialReceivedCallback = std::function<void(const AssetId& materialId, const MaterialData& material)>;

Callback for material received events.

using MaterialPropertyChangedCallback

using EntropyCanvas::CanvasClient::MaterialPropertyChangedCallback =
std::function<void(const AssetId& materialId, const std::string& propertyName,
                   const MaterialPropertyValue& value, uint64_t newVersion)>;

Callback for material property change events.

using EntityDestroyedCallback

using EntropyCanvas::CanvasClient::EntityDestroyedCallback = std::function<void(uint64_t entityId)>;

Callback for entity destruction events from server.

Parameters:

• entityId The destroyed entity ID

using EntityCreatedCallback

using EntropyCanvas::CanvasClient::EntityCreatedCallback =
std::function<void(uint64_t entityId, const std::string& appId, const std::string& typeName, uint64_t parentId,
                   const std::vector<EntropyEngine::Networking::NetworkSession::ComponentGroupData>& components,
                   const std::string& entityName)>;

Callback for entity creation events from server.

Parameters:

• entityId The created entity ID
• appId Application that created the entity
• typeName Type name of the entity
• parentId Parent entity ID (0 if root)
• components Component groups with their property metadata
• entityName Flecs entity name for client-side identification

using DestroySceneCallback

using EntropyCanvas::CanvasClient::DestroySceneCallback = std::function<void(bool success, const std::string& errorMessage)>;

Callback for scene destruction response.

using CreateSceneCallback

using EntropyCanvas::CanvasClient::CreateSceneCallback = std::function<void(bool success, uint64_t sceneId, const std::string& errorMessage)>;

Callback for scene creation response.

Parameters:

• success Whether the scene was created successfully
• sceneId The ID of the created scene (0 if failed)
• errorMessage Error message if creation failed

using AddEntityToSceneCallback

using EntropyCanvas::CanvasClient::AddEntityToSceneCallback = std::function<void(bool success, const std::string& errorMessage)>;

Callback for add entity to scene response.

Public Functions Documentation

function ~CanvasClient

~CanvasClient() override

function updateMaterialProperty

std::shared_ptr< UpdateMaterialHandle > updateMaterialProperty(
    const AssetId & materialId,
    const std::string & propertyName,
    const MaterialPropertyValue & value
)

Update a single material property.

Parameters:

• materialId ID of the material to update
• propertyName Name of the property to update
• value New property value

Return: Handle to track operation completion

function updateMaterialProperties

std::shared_ptr< UpdateMaterialHandle > updateMaterialProperties(
    const AssetId & materialId,
    const std::map< std::string, MaterialPropertyValue > & properties
)

Update multiple material properties atomically.

Parameters:

• materialId ID of the material to update
• properties Map of property names to values

Return: Handle to track operation completion

function unsubscribeMaterial

void unsubscribeMaterial(
    const AssetId & materialId
)

Unsubscribe from material updates.

Parameters:

• materialId ID of the material to unsubscribe from

function textureClient

inline TextureClient * textureClient()

Get the texture client for texture operations.

Returns nullptr if not connected.

function syncWorld

EntropyEngine::Networking::Result< void > syncWorld(
    flecs::world & world
)

Sync all entities in a Flecs world to CanvasEngine.

Parameters:

• world Flecs world to sync

Return: Result indicating success or failure

Iterates all entities with Transform and syncs them.

function syncEntity

EntropyEngine::Networking::Result< void > syncEntity(
    flecs::entity entity,
    uint64_t sceneId =0
)

Sync a Flecs entity to CanvasEngine.

Parameters:

• entity Flecs entity to sync
• sceneId Optional scene ID to add entity to (0 = use active scene)

Return: Result indicating success or failure

On first call: sends EntityCreated with property registrations for all components. On subsequent calls: sends PropertyUpdate for all component properties.

function subscribeMaterial

virtual void subscribeMaterial(
    const AssetId & materialId
) override

Subscribe to updates for a material.

Parameters:

• materialId ID of the material to subscribe to

Reimplements: EntropyCanvas::IDataProvider::subscribeMaterial

Called automatically when mesh with material binding is synced.

function shaderClient

inline ShaderClient * shaderClient()

Get the shader client for shader operations.

Returns nullptr if not connected.

function setupBuiltinSyncObservers

void setupBuiltinSyncObservers(
    flecs::world & world
)

Set up reactive sync observers for all built-in components.

Parameters:

• world The Flecs world to observe

Creates Flecs observers for Transform, Light, Mesh, and probe components. After calling this, component changes on synced entities automatically send network messages (ComponentAdded, ComponentRemoved, PropertyUpdate).

function setUsdSnapshotCallback

virtual void setUsdSnapshotCallback(
    UsdSnapshotCallback callback
) override

Set the callback for receiving raw USD scene data.

Reimplements: EntropyCanvas::IDataProvider::setUsdSnapshotCallback

This enables direct scene creation without per-property delta overhead.

function setSceneEnabled

void setSceneEnabled(
    uint64_t sceneId,
    bool enabled,
    SetSceneEnabledCallback callback
)

Enable or disable a scene.

Parameters:

• sceneId ID of the scene
• enabled Whether to enable or disable
• callback Called when server responds

Disabled scenes don’t render or process but can still receive updates.

function setMeshMaterialBindingCallback

void setMeshMaterialBindingCallback(
    MeshMaterialBindingCallback callback
)

Set callback for mesh material binding updates from other clients.

function setMaterialReceivedCallback

void setMaterialReceivedCallback(
    MaterialReceivedCallback callback
)

Set callback for receiving material data.

function setMaterialPropertyChangedCallback

void setMaterialPropertyChangedCallback(
    MaterialPropertyChangedCallback callback
)

Set callback for material property changes.

function setEntityDestroyedCallback

void setEntityDestroyedCallback(
    EntityDestroyedCallback callback
)

Set callback for entity destruction events.

function setEntityCreatedCallback

void setEntityCreatedCallback(
    EntityCreatedCallback callback
)

Set callback for entity creation events.

function setDeltaCallback

virtual void setDeltaCallback(
    DeltaCallback callback
) override

Set the callback for property delta updates.

Reimplements: EntropyCanvas::IDataProvider::setDeltaCallback

This will be called whenever a property changes on the server.

function setClientType

void setClientType(
    const std::string & clientType
)

Set the client type for handshake identification.

Parameters:

• clientType Client type string (e.g., “portal”, “viewer”, “tool”)

function setClientId

void setClientId(
    const std::string & clientId
)

Set the client ID for handshake identification.

Parameters:

• clientId Unique client identifier

function setActiveScene

void setActiveScene(
    uint64_t sceneId
)

Set the active scene for entity creation.

Parameters:

• sceneId Scene ID to use for new entities (0 = use server’s default scene)

New entities created via syncEntity() will be automatically added to this scene unless an explicit sceneId is provided to syncEntity().

function requestSnapshot

virtual void requestSnapshot(
    SnapshotCallback callback
) override

Request a full scene snapshot from the server.

Reimplements: EntropyCanvas::IDataProvider::requestSnapshot

The callback will be invoked when the snapshot is ready.

function registerSyncableComponent

template <typename T >
void registerSyncableComponent(
    flecs::world & world,
    const EntropyEngine::Networking::ComponentSchema & schema
)

Register a custom component type for reactive sync.

Parameters:

• world Flecs world to observe
• schema ComponentSchema with property definitions

Template Parameters:

• T Component type (must be a Flecs component)

Creates Flecs observers that automatically sync component changes for synced entities. Uses schema metadata for generic data building.

function poll

void poll()

Poll for network events.

Call this regularly from your main loop to process incoming messages.

function operator=

CanvasClient & operator=(
    const CanvasClient &
) =delete

function isEntitySynced

bool isEntitySynced(
    flecs::entity entity
) const

Check if an entity has been synced to CanvasEngine.

Parameters:

• entity Flecs entity to check

Return: true if entity has been synced at least once

function isConnected

virtual bool isConnected() const override

Check if connected to the server.

Reimplements: EntropyCanvas::IDataProvider::isConnected

function hasSyncObservers

bool hasSyncObservers() const

Check if reactive sync observers are active.

function getServerId

virtual uint32_t getServerId() const override

Get the server ID.

Reimplements: EntropyCanvas::IDataProvider::getServerId

function getEndpoint

inline const std::string & getEndpoint() const

Get the current connection endpoint.

function getDefaultEndpoint

static std::string getDefaultEndpoint()

Get the default CanvasEngine IPC endpoint for this platform.

Return: Default endpoint string

Platform behavior:

• Unix: /tmp/canvasengine.sock (or CANVASENGINE_IPC_ENDPOINT env var)
• Windows: .\pipe\canvasengine (or CANVASENGINE_IPC_ENDPOINT env var)

function getActiveScene

uint64_t getActiveScene() const

Get the currently active scene ID.

Return: Active scene ID (0 = using server’s default scene)

function disconnect

void disconnect()

Disconnect from the server.

function destroyScene

void destroyScene(
    uint64_t sceneId,
    DestroySceneCallback callback
)

Destroy a scene on the server.

Parameters:

• sceneId ID of the scene to destroy
• callback Called when server responds

function deleteEntity

EntropyEngine::Networking::Result< void > deleteEntity(
    flecs::entity entity
)

Mark an entity as deleted on CanvasEngine.

Parameters:

• entity Flecs entity to delete

Return: Result indicating success or failure

function createTransientScene

void createTransientScene(
    const std::string & sceneName,
    CreateSceneCallback callback
)

Create a transient scene on the server.

Parameters:

• sceneName Name for the scene
• callback Called when server responds with scene ID

Transient scenes are automatically cleaned up when this client disconnects.

function createPersistentScene

void createPersistentScene(
    const std::string & sceneName,
    CreateSceneCallback callback
)

Create a persistent scene on the server.

Parameters:

• sceneName Name for the scene
• callback Called when server responds with scene ID

Persistent scenes survive client disconnection.

function createMaterial

std::shared_ptr< CreateMaterialHandle > createMaterial(
    const MaterialData & material
)

Create a material on the server.

Parameters:

• material Material data to create

Return: Handle to track operation completion

function connectAndWait

bool connectAndWait(
    const std::string & endpoint ="",
    std::chrono::milliseconds timeout =std::chrono::seconds(5)
)

Connect to CanvasEngine and wait for handshake completion.

Parameters:

• endpoint Server endpoint (empty = use getDefaultEndpoint())
• timeout Max wait time for connection + handshake

Return: true if connected and handshake complete within timeout

This is a convenience method that combines connect() with polling until the connection is established and handshake completes.

function connect

bool connect(
    const std::string & endpoint
)

Connect to a CanvasEngine server.

Parameters:

• endpoint Server endpoint (socket path or signaling URL)

Return: true if connection initiated successfully

function bindMeshMaterials

std::shared_ptr< BindMeshMaterialsHandle > bindMeshMaterials(
    uint64_t entityId,
    const std::vector< AssetId > & materialIds
)

Bind materials to a mesh entity.

Parameters:

• entityId Entity with Mesh component
• materialIds Material AssetIds per submesh

Return: Handle to track operation completion

Each material ID corresponds to a submesh (index 0 = first submesh). The server will auto-subscribe this client to updates for the referenced materials.

function assetClient

inline AssetClient * assetClient()

Get the asset client for asset operations.

Returns nullptr if not connected.

function addEntityToScene

void addEntityToScene(
    uint64_t entityId,
    uint64_t sceneId,
    AddEntityToSceneCallback callback
)

Add an entity to a scene.

Parameters:

• entityId ID of the entity to add
• sceneId ID of the scene
• callback Called when server responds

function CanvasClient

CanvasClient()

function CanvasClient

explicit CanvasClient(
    const CanvasClientConfig & config
)

function CanvasClient

CanvasClient(
    const CanvasClient &
) =delete

---

Updated on 2026-01-26 at 16:50:32 -0500