| CRM64Pro GDK v0.17.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Scene LayerObject
Scene module » Scene Layer base

## Description

Object layer containing game objects with spatial partitioning.

Each SceneLayerObject manages a collection of SceneObject instances with efficient spatial queries via an internal grid. Supports render/update flags and deferred destruction.

## Classes
struct | CRM64Pro::SceneShapeData
| Shape geometry data for a SceneObject. More...
struct | CRM64Pro::SceneObjectTrigger
| Object trigger zone definition. More...
struct | CRM64Pro::SceneTriggerEvent
| Trigger event payload. More...
class | CRM64Pro::ISceneObjectFactory
| Factory interface for creating game objects from Tiled type strings. More...
class | CRM64Pro::SceneObject
| Base class for all Scene game objects. More...
class | CRM64Pro::SceneLayerObject
| Object layer containing game objects with spatial partitioning. More...

## Functions
HandleDLL void | CRM64Pro::SceneShapeData::calculateAABB (float objX, float objY, float objWidth, float objHeight)
| Recalculate AABB from object position and dimensions.
HandleDLL void | CRM64Pro::SceneObjectTrigger::addIncludeType (const string &sType)
| Add one type identifier to the include filter.
HandleDLL void | CRM64Pro::SceneObjectTrigger::addExcludeType (const string &sType)
| Add one type identifier to the exclude filter.
| CRM64Pro::SceneObject::SceneObject ()
| Default constructor.
virtual | CRM64Pro::SceneObject::~SceneObject ()
| Virtual destructor for proper cleanup of derived classes.
virtual void | CRM64Pro::SceneObject::initialize ()
| Called after TMX import populates all fields.
virtual void | CRM64Pro::SceneObject::update (Scene *pScene, SceneLayerContext &context)
| Called each frame when layer has UPDATE enabled.
virtual void | CRM64Pro::SceneObject::render (Scene *pScene, SceneLayerContext &context)
| Called each frame when layer has RENDER enabled and object is visible.
void | CRM64Pro::SceneObject::setPosition (float fNewX, float fNewY)
| Set object position and update spatial grid.
void | CRM64Pro::SceneObject::setSize (float fNewWidth, float fNewHeight)
| Set object size and update cached bounds.
void | CRM64Pro::SceneObject::setVisible (bool bNewVisible)
| Set object visibility.
const string & | CRM64Pro::SceneObject::getType () const
| Get the type identifier.
const string & | CRM64Pro::SceneObject::getName () const
| Get the object name.
bool | CRM64Pro::SceneObject::addTrigger (const SceneObjectTrigger &trigger)
| Add a trigger zone to this object.
bool | CRM64Pro::SceneObject::updateTrigger (const SceneObjectTrigger &trigger)
| Update an existing trigger by name.
bool | CRM64Pro::SceneObject::removeTrigger (const string &sName)
| Remove a trigger by name.
void | CRM64Pro::SceneObject::clearTriggers ()
| Remove all triggers.
bool | CRM64Pro::SceneObject::setTriggerEnabled (const string &sName, bool bEnabled)
| Enable or disable a trigger.
bool | CRM64Pro::SceneObject::getTrigger (const string &sName, SceneObjectTrigger *pOut) const
| Get a trigger definition by name.
Sint32 | CRM64Pro::SceneObject::getTriggerCount () const
| Get number of triggers assigned to this object.
void | CRM64Pro::SceneObject::setOnTriggerEvent (SCENE_OnTriggerEvent fn, void *pUserData=nullptr)
| Set trigger event callback.
void | CRM64Pro::SceneObject::recalculateBounds ()
| Recalculate cached AABB after shape or dimension changes.
bool | CRM64Pro::SceneObject::containsPoint (float px, float py) const
| Test if a point is inside this object's shape.
bool | CRM64Pro::SceneObject::overlapsObject (const SceneObject *pOther, SDL_FRect *pOverlap=nullptr) const
| Test if this object's AABB overlaps another object's AABB.
eSceneLayerType | CRM64Pro::SceneLayerObject::getType () const override
| Get the layer type.
Sint32 | CRM64Pro::SceneLayerObject::update (Scene *pEngine, SceneLayerContext &context) override
| Update object layer logic.
Sint32 | CRM64Pro::SceneLayerObject::render (Scene *pEngine, SceneLayerContext &context) override
| Render object layer content.
Sint32 | CRM64Pro::SceneLayerObject::addObject (SceneObject *pObj)
| Add an object to this layer.
bool | CRM64Pro::SceneLayerObject::closeObject (Sint32 id)
| Destroy an object by its ID.
void | CRM64Pro::SceneLayerObject::setSpatialGridCellSize (Sint32 size)
| Set the spatial grid cell size.
bool | CRM64Pro::SceneLayerObject::setSize (float width, float height)
| Set the logical size of the layer (in pixels).
void | CRM64Pro::SceneLayerObject::setRenderOrderMode (eSceneObjectRenderOrder mode)
| Set object rendering order policy.
eSceneObjectRenderOrder | CRM64Pro::SceneLayerObject::getRenderOrderMode () const
| Get object rendering order policy.
void | CRM64Pro::SceneLayerObject::queryRegion (float fX, float fY, float fW, float fH, vector< SceneObject * > &results)
| Query objects whose AABB overlaps a region.
SceneObject * | CRM64Pro::SceneLayerObject::getObjectByID (Sint32 iObjectID)
| Get object by Tiled ID.
Sint32 | CRM64Pro::SceneLayerObject::getObjectCount ()
| Get number of objects in this layer.
SceneObject * | CRM64Pro::SceneLayerObject::findFirstByType (const string &sType)
| Find first object matching an exact type string.
SceneObject * | CRM64Pro::SceneLayerObject::findFirstByName (const string &sName)
| Find first object matching an exact name string.
void | CRM64Pro::SceneLayerObject::findAllByType (const string &sType, vector< SceneObject * > &out)
| Find all objects matching an exact type string.
void | CRM64Pro::SceneLayerObject::findAllByName (const string &sName, vector< SceneObject * > &out)
| Find all objects matching an exact name string.
void | CRM64Pro::SceneLayerObject::setOnTriggerEvent (SceneObject::SCENE_OnTriggerEvent fn, void *pUserData=nullptr)
| Set a layer-wide trigger event callback.
virtual float | CRM64Pro::SceneLayerObject::getTotalWidth () const override
| Get layer total width in pixels.
virtual float | CRM64Pro::SceneLayerObject::getTotalHeight () const override
| Get layer total height in pixels.
void | CRM64Pro::Scene::setObjectFactory (ISceneObjectFactory *pFactory)
| Set the object factory for creating game objects from Tiled types.
ISceneObjectFactory * | CRM64Pro::Scene::getObjectFactory ()
| Get the current object factory.
bool | CRM64Pro::Scene::isObjectLayer (Sint32 iLayer)
| Check if a layer is an object layer.

## Function Documentation

## ◆ calculateAABB()

void CRM64Pro::SceneShapeData::calculateAABB | ( | float | objX,
|  | float | objY,
|  | float | objWidth,
|  | float | objHeight )

Recalculate AABB from object position and dimensions.

For polygons/polylines, calculates bounds from vertices. For other shapes, uses position and width/height.

Parameters

  objX | Object X position in world space.
  objY | Object Y position in world space.
  objWidth | Object width (ignored for polygon/polyline).
  objHeight | Object height (ignored for polygon/polyline).

## ◆ addIncludeType()

void CRM64Pro::SceneObjectTrigger::addIncludeType | ( | const string & | sType | ) |

Add one type identifier to the include filter.

Type is hashed internally exactly as provided. Empty strings are ignored.

Parameters

  sType | The type string to include.

## ◆ addExcludeType()

void CRM64Pro::SceneObjectTrigger::addExcludeType | ( | const string & | sType | ) |

Add one type identifier to the exclude filter.

Type is hashed internally exactly as provided. Empty strings are ignored.

Parameters

  sType | The type string to exclude.

## ◆ initialize()

void CRM64Pro::SceneObject::initialize | ( |  | ) |
| virtual

Called after TMX import populates all fields.

Override to parse properties, create sprites, initialize game state. Base implementation does nothing.

## ◆ update() [1/2]

void CRM64Pro::SceneObject::update | ( | Scene * | pScene,
|  | SceneLayerContext & | context )
| virtual

Called each frame when layer has UPDATE enabled.

Override to implement game logic, movement, AI, etc. Base implementation does nothing.

Parameters

  pScene | Pointer to the Scene instance.
  context | Layer context structure containing update state.

## ◆ render() [1/2]

void CRM64Pro::SceneObject::render | ( | Scene * | pScene,
|  | SceneLayerContext & | context )
| virtual

Called each frame when layer has RENDER enabled and object is visible.

Override to implement custom rendering. Base implementation renders the tile if gid is non-zero; otherwise does nothing.

Parameters

  pScene | Pointer to the Scene instance.
  context | Layer context structure containing render state.

Note
  During object-layer rendering, context.data.Object contains per-object render state (interpolated world transform and screen anchor), filled by SceneLayerObject::render().

## ◆ setPosition()

void CRM64Pro::SceneObject::setPosition | ( | float | fNewX,
|  | float | fNewY )

Set object position and update spatial grid.

Always use this method to move objects - direct modification of coordinates will desynchronize the object from the spatial grid.

Parameters

  fNewX | New X position in world pixels.
  fNewY | New Y position in world pixels.

## ◆ setSize() [1/2]

void CRM64Pro::SceneObject::setSize | ( | float | fNewWidth,
|  | float | fNewHeight )

Set object size and update cached bounds.

Parameters

  fNewWidth | New width in pixels.
  fNewHeight | New height in pixels.

## ◆ setVisible()

void CRM64Pro::SceneObject::setVisible | ( | bool | bNewVisible | ) |

Set object visibility.

Parameters

  bNewVisible | true to render, false to hide.

## ◆ getType() [1/2]

const string & CRM64Pro::SceneObject::getType | ( |  | ) | const

Get the type identifier.

Returns
  The type string.

## ◆ getName()

const string & CRM64Pro::SceneObject::getName | ( |  | ) | const

Get the object name.

Returns
  The object name string.

## ◆ addTrigger()

bool CRM64Pro::SceneObject::addTrigger | ( | const SceneObjectTrigger & | trigger | ) |

Add a trigger zone to this object.

Parameters

  trigger | Trigger definition.

Returns
  true on success, false on invalid input or duplicated name.

## ◆ updateTrigger()

bool CRM64Pro::SceneObject::updateTrigger | ( | const SceneObjectTrigger & | trigger | ) |

Update an existing trigger by name.

Parameters

  trigger | Trigger definition. sName selects the trigger to update.

Returns
  true on success, false if not found or invalid input.

## ◆ removeTrigger()

bool CRM64Pro::SceneObject::removeTrigger | ( | const string & | sName | ) |

Remove a trigger by name.

Parameters

  sName | Trigger name.

Returns
  true on success, false if not found.

## ◆ setTriggerEnabled()

bool CRM64Pro::SceneObject::setTriggerEnabled | ( | const string & | sName,
|  | bool | bEnabled )

Enable or disable a trigger.

Parameters

  sName | Trigger name.
  bEnabled | New enabled state.

Returns
  true on success, false if trigger is not found.

## ◆ getTrigger()

bool CRM64Pro::SceneObject::getTrigger | ( | const string & | sName,
|  | SceneObjectTrigger * | pOut ) const

Get a trigger definition by name.

Parameters

  sName | Trigger name.
  pOut | Destination structure.

Returns
  true on success, false if trigger is not found or pOut is null.

## ◆ getTriggerCount()

Sint32 CRM64Pro::SceneObject::getTriggerCount | ( |  | ) | const

Get number of triggers assigned to this object.

Returns
  The count of triggers.

## ◆ setOnTriggerEvent() [1/2]

void CRM64Pro::SceneObject::setOnTriggerEvent | ( | SCENE_OnTriggerEvent | fn,
|  | void * | pUserData = nullptr )

Set trigger event callback.

Object-level callback for this specific SceneObject instance. Called before layer/global trigger callbacks (dispatch order: object -> layer -> global).

Parameters

  fn | Callback function (nullptr to clear).
  pUserData | User data passed to callback.

## ◆ recalculateBounds()

void CRM64Pro::SceneObject::recalculateBounds | ( |  | ) |

Recalculate cached AABB after shape or dimension changes.

Call this if you modify shape.points directly.

## ◆ containsPoint()

bool CRM64Pro::SceneObject::containsPoint | ( | float | px,
|  | float | py ) const

Test if a point is inside this object's shape.

Uses precise shape geometry (not just AABB).

Parameters

  px | Point X coordinate in world space.
  py | Point Y coordinate in world space.

Returns
  true if point is inside the shape.

## ◆ overlapsObject()

bool CRM64Pro::SceneObject::overlapsObject | ( | const SceneObject * | pOther,
|  | SDL_FRect * | pOverlap = nullptr ) const

Test if this object's AABB overlaps another object's AABB.

Fast broad-phase overlap test using cached AABBs.

Parameters

  pOther | Pointer to other object.
  pOverlap | Optional pointer to a SDL_FRect filled with the intersection area if overlap occurs.

Returns
  true if AABBs overlap.

## ◆ getType() [2/2]

eSceneLayerType CRM64Pro::SceneLayerObject::getType | ( |  | ) | const
| override virtual

Get the layer type.

Returns
  SLT_OBJECT.

Implements CRM64Pro::SceneLayer.

## ◆ update() [2/2]

Sint32 CRM64Pro::SceneLayerObject::update | ( | Scene * | pEngine,
|  | SceneLayerContext & | context )
| override protected virtual

Update object layer logic.

Parameters

  pEngine | Pointer to the Scene instance.
  context | Layer context structure containing update state.

Returns
  0 on success, or a negative error code on failure.

Implements CRM64Pro::SceneLayer.

## ◆ render() [2/2]

Sint32 CRM64Pro::SceneLayerObject::render | ( | Scene * | pEngine,
|  | SceneLayerContext & | context )
| override protected virtual

Render object layer content.

Parameters

  pEngine | Pointer to the Scene instance.
  context | Layer context structure containing render state.

Returns
  0 on success, or a negative error code on failure.

Implements CRM64Pro::SceneLayer.

## ◆ addObject()

Sint32 CRM64Pro::SceneLayerObject::addObject | ( | SceneObject * | pObj | ) |

Add an object to this layer.

The object is queued for addition at the next synchronization point (usually end of update loop) to ensure thread-safety and prevent iterator invalidation. The layer takes ownership of the object and will release its memory upon destruction or closeObject(). Runtime-created objects are assigned a unique ID starting from 16384 to avoid collisions with Tiled IDs.

Parameters

  pObj | Object to add (must not be nullptr).

Returns
  The assigned Object ID (positive) on success, or a negative error code on failure.

## ◆ closeObject()

bool CRM64Pro::SceneLayerObject::closeObject | ( | Sint32 | id | ) |

Destroy an object by its ID.

The object is marked for removal and its memory will be safely released at the end of the frame. This method is thread-safe and safe to call during logic updates or from worker threads.

Parameters

  id | Object ID to destroy.

Returns
  true on success or false if the ID was not found.

## ◆ setSpatialGridCellSize()

void CRM64Pro::SceneLayerObject::setSpatialGridCellSize | ( | Sint32 | size | ) |

Set the spatial grid cell size.

Warning: This will clear the grid structure! Only use during initialization/loading.

Parameters

  size | New cell size in pixels.

## ◆ setSize() [2/2]

bool CRM64Pro::SceneLayerObject::setSize | ( | float | width,
|  | float | height )

Set the logical size of the layer (in pixels).

Parameters

  width | Total width in pixels.
  height | Total height in pixels.

Returns
  true on success or false on failure.

## ◆ setRenderOrderMode()

void CRM64Pro::SceneLayerObject::setRenderOrderMode | ( | eSceneObjectRenderOrder | mode | ) |

Set object rendering order policy.

Parameters

  mode | Draw order mode. See ::eSceneObjectRenderOrder.

## ◆ getRenderOrderMode()

eSceneObjectRenderOrder CRM64Pro::SceneLayerObject::getRenderOrderMode | ( |  | ) | const

Get object rendering order policy.

Returns
  Current draw order mode.

## ◆ queryRegion()

void CRM64Pro::SceneLayerObject::queryRegion | ( | float | fX,
|  | float | fY,
|  | float | fW,
|  | float | fH,
|  | vector< SceneObject * > & | results )

Query objects whose AABB overlaps a region.

Efficient spatial query using internal grid.

Parameters

  fX | Region X position in world pixels.
  fY | Region Y position in world pixels.
  fW | Region width in pixels.
  fH | Region height in pixels.
  results | Output vector filled with unique objects overlapping region.

## ◆ getObjectByID()

SceneObject * CRM64Pro::SceneLayerObject::getObjectByID | ( | Sint32 | iObjectID | ) |

Get object by Tiled ID.

Parameters

  iObjectID | Object ID to find.

Returns
  Pointer to object, or nullptr if not found.

## ◆ getObjectCount()

Sint32 CRM64Pro::SceneLayerObject::getObjectCount | ( |  | ) |

Get number of objects in this layer.

Returns
  The number of objects.

## ◆ findFirstByType()

SceneObject * CRM64Pro::SceneLayerObject::findFirstByType | ( | const string & | sType | ) |

Find first object matching an exact type string.

Exact case-sensitive match against the stored type string. Pending-destruction objects are ignored.

Parameters

  sType | Exact type string to match.

Returns
  Pointer to first matching object, or nullptr if not found.

## ◆ findFirstByName()

SceneObject * CRM64Pro::SceneLayerObject::findFirstByName | ( | const string & | sName | ) |

Find first object matching an exact name string.

Exact case-sensitive match against the stored object name. Pending-destruction objects are ignored.

Parameters

  sName | Exact object name to match.

Returns
  Pointer to first matching object, or nullptr if not found.

## ◆ findAllByType()

void CRM64Pro::SceneLayerObject::findAllByType | ( | const string & | sType,
|  | vector< SceneObject * > & | out )

Find all objects matching an exact type string.

Exact case-sensitive match against the stored type string. Pending-destruction objects are ignored.

Parameters

  sType | Exact type string to match.
  out | Output vector receiving matches (cleared by this method).

## ◆ findAllByName()

void CRM64Pro::SceneLayerObject::findAllByName | ( | const string & | sName,
|  | vector< SceneObject * > & | out )

Find all objects matching an exact name string.

Exact case-sensitive match against the stored object name. Pending-destruction objects are ignored.

Parameters

  sName | Exact object name to match.
  out | Output vector receiving matches (cleared by this method).

## ◆ setOnTriggerEvent() [2/2]

void CRM64Pro::SceneLayerObject::setOnTriggerEvent | ( | SceneObject::SCENE_OnTriggerEvent | fn,
|  | void * | pUserData = nullptr )

Set a layer-wide trigger event callback.

Layer-level callback for all trigger events generated in this SceneLayerObject. Called after object callback and before Scene global callback (dispatch order: object -> layer -> global).

Parameters

  fn | Callback function (nullptr to clear).
  pUserData | User data passed to callback.

## ◆ getTotalWidth()

float CRM64Pro::SceneLayerObject::getTotalWidth | ( |  | ) | const
| override virtual

Get layer total width in pixels.

Returns
  Width in pixels (max x + width of any object).

Reimplemented from CRM64Pro::SceneLayer.

## ◆ getTotalHeight()

float CRM64Pro::SceneLayerObject::getTotalHeight | ( |  | ) | const
| override virtual

Get layer total height in pixels.

Returns
  Height in pixels (max y + height of any object).

Reimplemented from CRM64Pro::SceneLayer.

## ◆ setObjectFactory()

void CRM64Pro::Scene::setObjectFactory | ( | ISceneObjectFactory * | pFactory | ) |

Set the object factory for creating game objects from Tiled types.

The factory is called during TMX import when objects with a "type" attribute are encountered. If no factory is set, or if the factory returns nullptr, a generic SceneObject is created.

Parameters

  pFactory | User-provided factory implementing ISceneObjectFactory. Must remain valid for Scene lifetime.

Note
  Factory can be set before or after loading TMX files. Setting nullptr disables custom object creation.

## ◆ getObjectFactory()

ISceneObjectFactory * CRM64Pro::Scene::getObjectFactory | ( |  | ) |

Get the current object factory.

Returns
  Pointer to the current factory, or nullptr if none set.

## ◆ isObjectLayer()

bool CRM64Pro::Scene::isObjectLayer | ( | Sint32 | iLayer | ) |

Check if a layer is an object layer.

Parameters

  iLayer | Layer index (1-based).

Returns
  true if the layer exists and is an object layer.