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

Loading...
Searching...
No Matches
Scene
Scene modules

## Description

Scene objects for 2D tile-based game development.

The Scene Core module is a robust 2D engine designed for creating complex tile-based games. It features a unified layer system that integrates standard Tile Maps, high-performance Object layers, and standalone Image layers into a single cohesive rendering pipeline.

## Classes
class | CRM64Pro::Scene
| Scene class. More...

## Functions
bool | CRM64Pro::Scene::info (Sint32 iMode=0) override
| Request detailed Scene object information.
const string & | CRM64Pro::Scene::getName () const override
| Get the name.
Sint32 | CRM64Pro::Scene::getID () const override
| Get the ID.
Sint32 | CRM64Pro::Scene::getWidth () const
| Get the total width of the level in pixels.
Sint32 | CRM64Pro::Scene::getHeight () const
| Get the total height of the level in pixels.
Sint32 | CRM64Pro::Scene::getLayerCount (eSceneLayerType eType=SLT_EMPTY) const
| Get the number of allocated layer slots.
Sint32 | CRM64Pro::Scene::createLayer (const string &sName, eSceneLayerType eType, Sint32 idLayer=-1, Sint32 iParam1=0, Sint32 iParam2=0)
| Create a new layer.
Sint32 | CRM64Pro::Scene::addLayer (SceneLayer *pLayer, Sint32 idLayer=-1)
| Add an existing layer instance.
bool | CRM64Pro::Scene::closeLayer (Sint32 iLayer)
| Close and destroy a layer.
bool | CRM64Pro::Scene::clear ()
| Free all resources of current map (layer maps and tilesets).
bool | CRM64Pro::Scene::setViewport (SDL_Rect *pRect)
| Set the desired viewport.
bool | CRM64Pro::Scene::getViewport (SDL_Rect *pOut) const
| Get the current viewport.
bool | CRM64Pro::Scene::setBackgroundColor (Uint32 iRGBA)
| Set background color.
Uint32 | CRM64Pro::Scene::getBackgroundColor () const
| Get background color.
string | CRM64Pro::Scene::getModificationDate () const
| Get the map modification date (last save date).
string | CRM64Pro::Scene::getCreationDate () const
| Get the map creation date (first save date).
bool | CRM64Pro::Scene::setLayerFeatures (Sint32 iLayer, eSceneLayerFeature eLF, bool bEnable)
| Set the layer features.
eSceneLayerFeature | CRM64Pro::Scene::getLayerFeatures (Sint32 iLayer) const
| Get the layer features.
bool | CRM64Pro::Scene::pause ()
| Pause all active layers.
bool | CRM64Pro::Scene::resume ()
| Resume all active layers.
bool | CRM64Pro::Scene::setLayerAlphaMod (Sint32 iLayer, Sint32 iAlpha)
| Set layer alpha modulation used for rendering this layer.
Sint32 | CRM64Pro::Scene::getLayerAlphaMod (Sint32 iLayer) const
| Get layer alpha modulation.
bool | CRM64Pro::Scene::setLayerParallaxRatio (Sint32 iLayer, float fPRX, float fPRY)
| Set the layer parallax ratio.
Sint32 | CRM64Pro::Scene::getLayerParallaxRatio (Sint32 iLayer, float *fPRX, float *fPRY) const
| Get current layer parallax ratio.
bool | CRM64Pro::Scene::setCameraMode (Sint32 iLayer, eSceneCameraMode eMode)
| Set camera mode for a layer.
eSceneCameraMode | CRM64Pro::Scene::getCameraMode (Sint32 iLayer) const
| Get camera mode for a layer.
bool | CRM64Pro::Scene::setCameraParams (Sint32 iLayer, const SceneCameraParams &rParams)
| Set camera parameters for a layer.
bool | CRM64Pro::Scene::getCameraParams (Sint32 iLayer, SceneCameraParams *pOut) const
| Get camera parameters for a layer.
bool | CRM64Pro::Scene::setCameraTarget (Sint32 iLayer, Sint32 idTargetObjectLayer, Sint32 idTargetObject)
| Set camera target by object layer and object ID.
bool | CRM64Pro::Scene::setCameraTarget (Sint32 iLayer, SceneObject *pTarget)
| Set camera target by object pointer.
bool | CRM64Pro::Scene::clearCameraTarget (Sint32 iLayer)
| Clear camera target binding for a layer.
bool | CRM64Pro::Scene::setCameraPosition (Sint32 iLayer, float fX, float fY, bool bDisableNextSmooth=false)
| Set camera absolute position and force manual mode.
bool | CRM64Pro::Scene::setCameraBounds (Sint32 iLayer, const SDL_FRect *pBounds)
| Set optional camera clamp bounds override for a layer.
bool | CRM64Pro::Scene::getCameraBounds (Sint32 iLayer, SDL_FRect *pOut) const
| Get explicit camera clamp bounds override for a layer.
bool | CRM64Pro::Scene::setCameraOffsetCallback (Sint32 iLayer, SceneCameraOffsetCallback fnCallback)
| Set offset callback for ::SCM_OFFSET mode.
bool | CRM64Pro::Scene::setCameraShake (Sint32 iLayer, float fAmplitudePX, Uint32 iDurationMS, float fFalloff=5.0f)
| Set a transient render-only camera shake for a layer.
bool | CRM64Pro::Scene::clearCameraShake (Sint32 iLayer)
| Clear active camera shake on a layer.
Sint32 | CRM64Pro::Scene::setLayerPosition (Sint32 iLayer, const Position &rPosX=Position(PH_KEEP), const Position &rPosY=Position(PH_KEEP), bool *bMoved=nullptr)
| Set the layer absolute position (in pixels).
Sint32 | CRM64Pro::Scene::getLayerPosition (Sint32 iLayer, float *fX, float *fY) const
| Get the current layer position (in pixels).
eSceneLayerType | CRM64Pro::Scene::getLayerType (Sint32 iLayer) const
| Get the type of a specific layer.
SceneLayerTile * | CRM64Pro::Scene::accessLayerTile (Sint32 iLayer)
| Get a tile layer by Scene layer index.
SceneLayerObject * | CRM64Pro::Scene::accessLayerObject (Sint32 iLayer)
| Get an object layer by Scene layer index.
SceneLayerImage * | CRM64Pro::Scene::accessLayerImage (Sint32 iLayer)
| Get an image layer by Scene layer index.
bool | CRM64Pro::Scene::setLayerOnUpdateEnd (Sint32 iLayer, SceneLayerCallback fnCallback)
| Set an event function (onUpdateEnd) to be called when the engine finishes updating the layer.
SceneLayerCallback | CRM64Pro::Scene::getLayerOnUpdateEnd (Sint32 iLayer) const
| Get current onUpdateEnd event function if any.
bool | CRM64Pro::Scene::setLayerOnRenderEnd (Sint32 iLayer, SceneLayerCallback fnCallback)
| Set an event function (onRenderEnd) to be called when the engine finishes rendering the layer.
SceneLayerCallback | CRM64Pro::Scene::getLayerOnRenderEnd (Sint32 iLayer) const
| Get current onRenderEnd event function if any.
void | CRM64Pro::Scene::setOnTriggerEvent (SceneObject::TriggerEventCallback fnCallback)
| Set a global trigger event callback.
bool | CRM64Pro::Scene::getLayerName (Sint32 iLayer, string &sName) const
| Get the layer name.
bool | CRM64Pro::Scene::setLayerName (Sint32 iLayer, const string &sName)
| Set a new layer name.
bool | CRM64Pro::Scene::setDebugOverlay (eSceneDebugOverlay eFlags, bool bEnable)
| Enable or disable one or more unified debug overlay flags.
bool | CRM64Pro::Scene::isDebugOverlayEnabled (eSceneDebugOverlay eFlags) const
| Check if all requested debug overlay flags are enabled.
bool | CRM64Pro::Scene::setDebugOverlayColor (eSceneDebugOverlay eFlag, Uint32 iColor)
| Set debug overlay color for a specific overlay flag.
Uint32 | CRM64Pro::Scene::getDebugOverlayColor (eSceneDebugOverlay eFlag) const
| Get debug overlay color for a specific overlay flag.
bool | CRM64Pro::Scene::screenToWorld (Sint32 iScreenX, Sint32 iScreenY, float *fWorldX, float *fWorldY, Sint32 iLayer=0) const
| Convert screen coordinates to world coordinates.
bool | CRM64Pro::Scene::screenToCell (Sint32 iScreenX, Sint32 iScreenY, Sint32 *iCellX, Sint32 *iCellY, Sint32 iLayer=0) const
| Convert screen coordinates to tile cell indices.
bool | CRM64Pro::Scene::worldToScreen (float fWorldX, float fWorldY, float *fScreenX, float *fScreenY, Sint32 iLayer=0)
| Convert world coordinates to screen coordinates.
bool | CRM64Pro::Scene::mouseToWorld (float *fWorldX, float *fWorldY, Sint32 iLayer=0) const
| Convert current mouse position to world coordinates.
bool | CRM64Pro::Scene::mouseToCell (Sint32 *iCellX, Sint32 *iCellY, Sint32 iLayer=0) const
| Convert current mouse position to tile cell indices.
Sint32 | CRM64Pro::Scene::update (Sint32 iLayer=0)
| Update status of the Scene.
Sint32 | CRM64Pro::Scene::render (Sint32 iLayer=0, Sint32 idRes=0)
| Render the visible layers.

## Function Documentation

## ◆ info()

bool CRM64Pro::Scene::info | ( | Sint32 | iMode = 0 | ) |
| override

Request detailed Scene object information.

Writes information to the default log.

Parameters

  iMode | 0 (default) to display all layers. A specific 1-based layer ID displays only that layer.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::Scene::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Sint32 CRM64Pro::Scene::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ getWidth()

Sint32 CRM64Pro::Scene::getWidth | ( |  | ) | const

Get the total width of the level in pixels.

Calculates the maximum width based on the largest layer (map or image).

Returns
  Total width in pixels.

## ◆ getHeight()

Sint32 CRM64Pro::Scene::getHeight | ( |  | ) | const

Get the total height of the level in pixels.

Calculates the maximum height based on the largest layer (map or image).

Returns
  Total height in pixels.

## ◆ getLayerCount()

Sint32 CRM64Pro::Scene::getLayerCount | ( | eSceneLayerType | eType = SLT_EMPTY | ) | const

Get the number of allocated layer slots.

Returns the total number of layer slots currently allocated in the engine.

Note
  This count includes empty slots (nullptr) if layers were created with non-continuous IDs. Use getLayerType() to check if a specific slot is in use.

Parameters

  eType | Optional layer type filter. SLT_EMPTY (default): Returns total allocated slots (size of layer vector). Other values: Returns the count of active layers matching that specific type.

Returns
  The number of layers.

## ◆ createLayer()

Sint32 CRM64Pro::Scene::createLayer | ( | const string & | sName,
|  | eSceneLayerType | eType,
|  | Sint32 | idLayer = -1,
|  | Sint32 | iParam1 = 0,
|  | Sint32 | iParam2 = 0 )

Create a new layer.

Factory method for creating layers. Scene owns all created layers.

Parameters

  sName | Layer name for identification.
  eType | Layer type: SLT_TILE, SLT_OBJECT, or SLT_IMAGE.
  idLayer | Optional layer ID to assign. -1 (default) auto-assigns next available slot. If specified ID is occupied, creation fails. If ID > current count, empty layers are inserted.
  iParam1 | Type-specific parameter: SLT_TILE: map width (in cells) SLT_OBJECT: spatial grid cell size (0 = default 64) SLT_IMAGE: ignored
  iParam2 | Type-specific parameter: SLT_TILE: map height (in cells) SLT_OBJECT: ignored SLT_IMAGE: ignored

Returns
  Greater than 0 on success (the Layer id), or a negative error code on failure.

## ◆ addLayer()

Sint32 CRM64Pro::Scene::addLayer | ( | SceneLayer * | pLayer,
|  | Sint32 | idLayer = -1 )

Add an existing layer instance.

Attach a pre-created layer (standard or user-derived) to the engine. The engine takes ownership of the pointer and will delete it upon destruction or closeLayer().

Parameters

  pLayer | Pointer to the layer object (must be allocated with new(std::nothrow)).
  idLayer | Optional layer ID. -1 (default) auto-assigns next available slot.

Returns
  Greater than 0 on success (the Layer id), or a negative error code on failure.

Warning
  Do not manually delete the layer after passing it to this method.

## ◆ closeLayer()

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

Close and destroy a layer.

Releases the tile layer and resets all layer settings, leaving the slot empty and ready for reuse. The engine takes ownership of the layer pointer when added and will delete it here.

Parameters

  iLayer | Selected layer to close (from 1 to number of allocated layers).

Returns
  true on success, or false on failure.

## ◆ clear()

bool CRM64Pro::Scene::clear | ( |  | ) |

Free all resources of current map (layer maps and tilesets).

Resets the current map. All layers are reset but layer slots are kept. Preserves viewport, map name and number of allocated layers.

Returns
  true on success, or false on failure.

## ◆ setViewport()

bool CRM64Pro::Scene::setViewport | ( | SDL_Rect * | pRect | ) |

Set the desired viewport.

You can change the viewport at any time even while you are rendering your application. The width and height of the viewport cannot be greater than values of the smallest layer (excluding the ones with looping features), otherwise, it will be automatically adjusted.

Parameters

  pRect | Pointer to SDL_Rect with the desired viewport. If the rect width or height is 0, it will use the whole target (a valid screen or image handle).

Returns
  true on success, or false on failure.

## ◆ getViewport()

bool CRM64Pro::Scene::getViewport | ( | SDL_Rect * | pOut | ) | const

Get the current viewport.

Parameters

  pOut | Pointer to SDL_Rect that receives the current effective viewport.

Returns
  true on success or false on failure (e.g. out is nullptr).

## ◆ setBackgroundColor()

bool CRM64Pro::Scene::setBackgroundColor | ( | Uint32 | iRGBA | ) |

Set background color.

Parameters

  iRGBA | background color to set in the format RGBA. When A is 0 (totally transparent), the background color is disabled.

Returns
  true on success, or false on failure.

## ◆ getBackgroundColor()

Uint32 CRM64Pro::Scene::getBackgroundColor | ( |  | ) | const

Get background color.

Returns
  the background color in format RGBA. When A is 0 (totally transparent, the background color is disabled)

## ◆ getModificationDate()

string CRM64Pro::Scene::getModificationDate | ( |  | ) | const

Get the map modification date (last save date).

Returns
  a string containing the date.

## ◆ getCreationDate()

string CRM64Pro::Scene::getCreationDate | ( |  | ) | const

Get the map creation date (first save date).

Returns
  a string containing the date.

## ◆ setLayerFeatures()

bool CRM64Pro::Scene::setLayerFeatures | ( | Sint32 | iLayer,
|  | eSceneLayerFeature | eLF,
|  | bool | bEnable )

Set the layer features.

Parameters

  iLayer | Layer index (from 1 to number of allocated layers).
  eLF | Feature or features to be enabled or disabled (can be combined using bitwise OR). Check ::eSceneLayerFeature enum for further information.
  bEnable | true for enabling the given features or false for disabling them.

Returns
  true on success, or false on failure.

Note
  Passing ::SLF_NONE clears all layer features. In this case, `bEnable` is ignored.
  Enabling ::SLF_RENDER implicitly enables ::SLF_UPDATE for that layer.
  Disabling ::SLF_RENDER does not disable ::SLF_UPDATE.

## ◆ getLayerFeatures()

eSceneLayerFeature CRM64Pro::Scene::getLayerFeatures | ( | Sint32 | iLayer | ) | const

Get the layer features.

Parameters

  iLayer | Layer index (from 1 to number of allocated layers).

Returns
  A ::eSceneLayerFeature enum containing all currently enabled features.

## ◆ pause()

bool CRM64Pro::Scene::pause | ( |  | ) |

Pause all active layers.

Enables ::SLF_PAUSE on all non-disabled layers. After calling this method, specific layers can be re-enabled by disabling ::SLF_PAUSE on those layers (e.g., keep GUI layer active during modal dialogs).

Returns
  true on success, or false on failure.

## ◆ resume()

bool CRM64Pro::Scene::resume | ( |  | ) |

Resume all active layers.

Disables ::SLF_PAUSE on all non-disabled layers.

Returns
  true on success, or false on failure.

## ◆ setLayerAlphaMod()

bool CRM64Pro::Scene::setLayerAlphaMod | ( | Sint32 | iLayer,
|  | Sint32 | iAlpha )

Set layer alpha modulation used for rendering this layer.

Parameters

  iLayer | Selected layer to set the alpha value (from 1 to number of allocated layers).
  iAlpha | It ranges from 255 (opaque) to 0 (fully transparent).

Returns
  true on success, or false on failure.

## ◆ getLayerAlphaMod()

Sint32 CRM64Pro::Scene::getLayerAlphaMod | ( | Sint32 | iLayer | ) | const

Get layer alpha modulation.

Parameters

  iLayer | Selected layer to get the alpha value (from 1 to number of allocated layers)

Returns
  It ranges from 255 (opaque) to 0 (fully transparent) or a negative error code on failure.

## ◆ setLayerParallaxRatio()

bool CRM64Pro::Scene::setLayerParallaxRatio | ( | Sint32 | iLayer,
|  | float | fPRX,
|  | float | fPRY )

Set the layer parallax ratio.

Changes the real speed of any layer relative to the camera movement.

Parameters

  iLayer | Selected layer to set the parallax ratio (from 1 to number of allocated layers).
  fPRX | Parallax ratio on X axis. 1.0 moves at standard speed. < 1.0 moves slower (background). > 1.0 moves faster (foreground). 0.0 makes the layer independent (HUD/static).
  fPRY | Parallax ratio on Y axis. 1.0 moves at standard speed. < 1.0 moves slower (background). > 1.0 moves faster (foreground). 0.0 makes the layer independent (HUD/static).

Returns
  true on success, or false on failure.

## ◆ getLayerParallaxRatio()

Sint32 CRM64Pro::Scene::getLayerParallaxRatio | ( | Sint32 | iLayer,
|  | float * | fPRX,
|  | float * | fPRY ) const

Get current layer parallax ratio.

Parameters

  iLayer | Selected layer to get the parallax ratio (from 1 to number of allocated layers).
  fPRX | a float pointer filled in with parallax ratio on X axis. If nullptr is passed, the method ignores the retrieving of this value.
  fPRY | a float pointer filled in with parallax ratio on Y axis. If nullptr is passed, the method ignores the retrieving of this value.

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

## ◆ setCameraMode()

bool CRM64Pro::Scene::setCameraMode | ( | Sint32 | iLayer,
|  | eSceneCameraMode | eMode )

Set camera mode for a layer.

Camera mode is processed during update() for the selected layer. When switching from ::SCM_MANUAL to a target-based automatic mode, ensure a target is bound through setCameraTarget().

Note
  ::SCM_AUTOSCROLL does not require a camera target.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  eMode | Camera mode to assign.

Returns
  true on success, or false on failure.

## ◆ getCameraMode()

eSceneCameraMode CRM64Pro::Scene::getCameraMode | ( | Sint32 | iLayer | ) | const

Get camera mode for a layer.

Parameters

  iLayer | Layer index (1..getLayerCount()).

Returns
  Current camera mode, or ::SCM_MANUAL if layer is invalid.

## ◆ setCameraParams()

bool CRM64Pro::Scene::setCameraParams | ( | Sint32 | iLayer,
|  | const SceneCameraParams & | rParams )

Set camera parameters for a layer.

Parameters are sanitized (anchors clamped to [0..1], deadzone size >= 0, damping >= 0). Applies to all non-manual camera modes.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  rParams | Camera parameters.

Returns
  true on success, or false on failure.

## ◆ getCameraParams()

bool CRM64Pro::Scene::getCameraParams | ( | Sint32 | iLayer,
|  | SceneCameraParams * | pOut ) const

Get camera parameters for a layer.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  pOut | Pointer to destination parameters structure.

Returns
  true on success, or false on failure.

## ◆ setCameraTarget() [1/2]

bool CRM64Pro::Scene::setCameraTarget | ( | Sint32 | iLayer,
|  | Sint32 | idTargetObjectLayer,
|  | Sint32 | idTargetObject )

Set camera target by object layer and object ID.

This is the recommended binding mode because IDs remain valid across update/render frames. The target object must exist at the time of this call.

Parameters

  iLayer | Camera-controlled layer index (1..getLayerCount()).
  idTargetObjectLayer | Object layer index containing the target.
  idTargetObject | Object ID inside the target object layer.

Returns
  true on success, or false on failure.

## ◆ setCameraTarget() [2/2]

bool CRM64Pro::Scene::setCameraTarget | ( | Sint32 | iLayer,
|  | SceneObject * | pTarget )

Set camera target by object pointer.

Convenience overload. The engine resolves the pointer to (object layer, object id) at call time. If the object cannot be resolved, the method fails and target remains unchanged.

Note
  This method stores the resolved layer/id pair (not the raw pointer) for stable runtime behavior.

Parameters

  iLayer | Camera-controlled layer index (1..getLayerCount()).
  pTarget | Target object pointer.

Returns
  true on success, or false on failure.

## ◆ clearCameraTarget()

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

Clear camera target binding for a layer.

Parameters

  iLayer | Layer index (1..getLayerCount()).

Returns
  true on success, or false on failure.

## ◆ setCameraPosition()

bool CRM64Pro::Scene::setCameraPosition | ( | Sint32 | iLayer,
|  | float | fX,
|  | float | fY,
|  | bool | bDisableNextSmooth = false )

Set camera absolute position and force manual mode.

This method always switches the selected layer camera mode to ::SCM_MANUAL. It is intended for explicit camera control, teleports, cutscene jumps, and modal transitions.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  fX | Absolute camera X position in world pixels.
  fY | Absolute camera Y position in world pixels.
  bDisableNextSmooth | If true, disables one-frame interpolation to avoid visual trail after teleports/cut transitions.

Returns
  true on success, or false on failure.

## ◆ setCameraBounds()

bool CRM64Pro::Scene::setCameraBounds | ( | Sint32 | iLayer,
|  | const SDL_FRect * | pBounds )

Set optional camera clamp bounds override for a layer.

If pBounds is nullptr, explicit bounds override is removed and automatic layer/world bounds are used. This override is only applied when SceneCameraParams::bClampToBounds is true.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  pBounds | Optional pointer to world-space bounds rectangle.

Returns
  true on success, or false on failure.

## ◆ getCameraBounds()

bool CRM64Pro::Scene::getCameraBounds | ( | Sint32 | iLayer,
|  | SDL_FRect * | pOut ) const

Get explicit camera clamp bounds override for a layer.

Returns only explicitly assigned bounds. If no override is defined, method returns false.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  pOut | Pointer to destination rect.

Returns
  true if explicit bounds exist and were copied, false otherwise.

## ◆ setCameraOffsetCallback()

bool CRM64Pro::Scene::setCameraOffsetCallback | ( | Sint32 | iLayer,
|  | SceneCameraOffsetCallback | fnCallback )

Set offset callback for ::SCM_OFFSET mode.

The callback is evaluated each update tick in ::SCM_OFFSET mode. On callback failure (return false), offset {0,0} is used for that tick.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  fnCallback | Callback function, or an empty callback to disable the offset callback.

Returns
  true on success, or false on failure.

## ◆ setCameraShake()

bool CRM64Pro::Scene::setCameraShake | ( | Sint32 | iLayer,
|  | float | fAmplitudePX,
|  | Uint32 | iDurationMS,
|  | float | fFalloff = 5.0f )

Set a transient render-only camera shake for a layer.

Shake is applied additively during render interpolation and does not alter logic/world positions.

Parameters

  iLayer | Layer index (1..getLayerCount()).
  fAmplitudePX | Maximum shake amplitude in pixels.
  iDurationMS | Shake duration in milliseconds.
  fFalloff | Exponential decay factor (>= 0). Larger values decay faster.

Returns
  true on success, or false on failure.

## ◆ clearCameraShake()

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

Clear active camera shake on a layer.

Parameters

  iLayer | Layer index (1..getLayerCount()).

Returns
  true on success, or false on failure.

## ◆ setLayerPosition()

Sint32 CRM64Pro::Scene::setLayerPosition | ( | Sint32 | iLayer,
|  | const Position & | rPosX = Position(PH_KEEP),
|  | const Position & | rPosY = Position(PH_KEEP),
|  | bool * | bMoved = nullptr )

Set the layer absolute position (in pixels).

Changes position for linked layers according to parallax ratios. Layers with parallax ratio 0.0 are independent. If this call effectively changes the layer position, the selected layer camera mode is switched to ::SCM_MANUAL. Requires valid base tile layer or image set.

Parameters

  iLayer | layer index (1 to getLayerCount()).
  rPosX | Position struct with x position. Can be absolute (float) or use ::PH_LEFT/::PH_RIGHT/::PH_CENTER/::PH_KEEP helpers.
  rPosY | Position struct with y position. Can be absolute (float) or use ::PH_TOP/::PH_BOTTOM/::PH_CENTER/::PH_KEEP helpers.
  bMoved | optional pointer filled with true when the layer position changed, or false otherwise.

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

Note
  No-op calls (e.g. ::PH_KEEP/::PH_KEEP, unchanged/clamped result) do not change camera mode.
  Supports implicit conversion from float: setLayerPosition(1, 100.0f, 200.0f) or explicit helpers: setLayerPosition(1, Position(PH_CENTER), Position(PH_KEEP))

## ◆ getLayerPosition()

Sint32 CRM64Pro::Scene::getLayerPosition | ( | Sint32 | iLayer,
|  | float * | fX,
|  | float * | fY ) const

Get the current layer position (in pixels).

Parameters

  iLayer | Selected layer to get its current position (from 1 to number of allocated layers).
  fX | Pointer to float var to store the position on X axis. nullptr if it should not be retrieved.
  fY | Pointer to float var to store the position on Y axis. nullptr if it should not be retrieved.

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

## ◆ getLayerType()

eSceneLayerType CRM64Pro::Scene::getLayerType | ( | Sint32 | iLayer | ) | const

Get the type of a specific layer.

Useful for iterating through layers to check their status without casting.

Parameters

  iLayer | Layer index (from 1 to getLayerCount()).

Returns
  The layer type (SLT_TILE, SLT_OBJECT, SLT_IMAGE) or SLT_EMPTY if the layer is free/null or out of bounds.

## ◆ accessLayerTile()

SceneLayerTile * CRM64Pro::Scene::accessLayerTile | ( | Sint32 | iLayer | ) |

Get a tile layer by Scene layer index.

Parameters

  iLayer | Scene layer index (1-based, as used by other layer methods).

Returns
  Borrowed pointer to the tile layer, or nullptr if the layer has no tile or is out of range.

Note
  The returned pointer must not be deleted. It remains valid until the layer is closed or the Scene is destroyed.

## ◆ accessLayerObject()

SceneLayerObject * CRM64Pro::Scene::accessLayerObject | ( | Sint32 | iLayer | ) |

Get an object layer by Scene layer index.

Convenience method to get the object layer associated with a Scene layer.

Parameters

  iLayer | Scene layer index (1-based, as used by other layer methods).

Returns
  Borrowed pointer to the object layer, or nullptr if the layer has no objects or is out of range.

Note
  The returned pointer must not be deleted. It remains valid until the layer is closed or the Scene is destroyed.

## ◆ accessLayerImage()

SceneLayerImage * CRM64Pro::Scene::accessLayerImage | ( | Sint32 | iLayer | ) |

Get an image layer by Scene layer index.

Parameters

  iLayer | Scene layer index (1-based, as used by other layer methods).

Returns
  Borrowed pointer to the image layer, or nullptr if the layer has no image or is out of range.

Note
  The returned pointer must not be deleted. It remains valid until the layer is closed or the Scene is destroyed.

## ◆ setLayerOnUpdateEnd()

bool CRM64Pro::Scene::setLayerOnUpdateEnd | ( | Sint32 | iLayer,
|  | SceneLayerCallback | fnCallback )

Set an event function (onUpdateEnd) to be called when the engine finishes updating the layer.

Use an empty callback to remove a previous onUpdateEnd event function.

Parameters

  iLayer | Layer index used to set the event function (from 1 to number of allocated layers).
  fnCallback | Callback function, or an empty callback to clear.

Returns
  true on success, or false on failure.

## ◆ getLayerOnUpdateEnd()

SceneLayerCallback CRM64Pro::Scene::getLayerOnUpdateEnd | ( | Sint32 | iLayer | ) | const

Get current onUpdateEnd event function if any.

Parameters

  iLayer | Selected layer to get current onUpdateEnd event function (from 1 to number of allocated layers).

Returns
  Current event callback, or an empty callback if none is assigned.

## ◆ setLayerOnRenderEnd()

bool CRM64Pro::Scene::setLayerOnRenderEnd | ( | Sint32 | iLayer,
|  | SceneLayerCallback | fnCallback )

Set an event function (onRenderEnd) to be called when the engine finishes rendering the layer.

Use an empty callback to remove a previous onRenderEnd event function.

Parameters

  iLayer | Layer index used to set the event function (from 1 to number of allocated layers).
  fnCallback | Callback function, or an empty callback to clear.

Returns
  true on success, or false on failure.

## ◆ getLayerOnRenderEnd()

SceneLayerCallback CRM64Pro::Scene::getLayerOnRenderEnd | ( | Sint32 | iLayer | ) | const

Get current onRenderEnd event function if any.

Parameters

  iLayer | Selected layer to get current onRenderEnd event function (from 1 to number of allocated layers).

Returns
  Current event callback, or an empty callback if none is assigned.

## ◆ setOnTriggerEvent()

void CRM64Pro::Scene::setOnTriggerEvent | ( | SceneObject::TriggerEventCallback | fnCallback | ) |

Set a global trigger event callback.

Global callback for every trigger event generated by any object layer in this Scene. Called after object and layer callbacks (dispatch order: object -> layer -> global).

Parameters

  fnCallback | Callback function, or an empty callback to clear.

## ◆ getLayerName()

bool CRM64Pro::Scene::getLayerName | ( | Sint32 | iLayer,
|  | string & | sName ) const

Get the layer name.

Parameters

  iLayer | Selected layer to get its name (from 1 to number of allocated layers).
  sName | a string containing the layer name.

Returns
  true on success, or false on failure.

## ◆ setLayerName()

bool CRM64Pro::Scene::setLayerName | ( | Sint32 | iLayer,
|  | const string & | sName )

Set a new layer name.

Parameters

  iLayer | Selected layer to set its name (from 1 to number of allocated layers).
  sName | Layer name, e.g. 'layer0'.

Returns
  true on success, or false on failure.

## ◆ setDebugOverlay()

bool CRM64Pro::Scene::setDebugOverlay | ( | eSceneDebugOverlay | eFlags,
|  | bool | bEnable )

Enable or disable one or more unified debug overlay flags.

Parameters

  eFlags | Overlay flag or combination of flags.
  bEnable | true to enable, false to disable.

Returns
  true on success.

## ◆ isDebugOverlayEnabled()

bool CRM64Pro::Scene::isDebugOverlayEnabled | ( | eSceneDebugOverlay | eFlags | ) | const

Check if all requested debug overlay flags are enabled.

Parameters

  eFlags | Overlay flag or combination of flags.

Returns
  true when all requested flags are enabled, otherwise false.

## ◆ setDebugOverlayColor()

bool CRM64Pro::Scene::setDebugOverlayColor | ( | eSceneDebugOverlay | eFlag,
|  | Uint32 | iColor )

Set debug overlay color for a specific overlay flag.

Parameters

  eFlag | Single overlay flag (SDO_OBJECT_AABB, SDO_TILE_CELLGRID, SDO_TRIGGER_ZONES, SDO_CAMERA_DEADZONE).
  iColor | RGBA color (0xRRGGBBAA).

Returns
  true on success or false on invalid flag.

## ◆ getDebugOverlayColor()

Uint32 CRM64Pro::Scene::getDebugOverlayColor | ( | eSceneDebugOverlay | eFlag | ) | const

Get debug overlay color for a specific overlay flag.

Parameters

  eFlag | Single overlay flag.

Returns
  RGBA color (0xRRGGBBAA), or 0 on invalid flag.

## ◆ screenToWorld()

bool CRM64Pro::Scene::screenToWorld | ( | Sint32 | iScreenX,
|  | Sint32 | iScreenY,
|  | float * | fWorldX,
|  | float * | fWorldY,
|  | Sint32 | iLayer = 0 ) const

Convert screen coordinates to world coordinates.

Parameters

  iScreenX | Screen X coordinate.
  iScreenY | Screen Y coordinate.
  fWorldX | Optional output world X.
  fWorldY | Optional output world Y.
  iLayer | Layer index (1..getLayerCount()). Use 0 to auto-select the camera-authority layer first (fallback: first render-enabled layer).

Returns
  true on success or false on failure (invalid layer, non-render layer, or outside viewport).

## ◆ screenToCell()

bool CRM64Pro::Scene::screenToCell | ( | Sint32 | iScreenX,
|  | Sint32 | iScreenY,
|  | Sint32 * | iCellX,
|  | Sint32 * | iCellY,
|  | Sint32 | iLayer = 0 ) const

Convert screen coordinates to tile cell indices.

Parameters

  iScreenX | Screen X coordinate.
  iScreenY | Screen Y coordinate.
  iCellX | Optional output cell X.
  iCellY | Optional output cell Y.
  iLayer | Layer index (1..getLayerCount()). Use 0 to auto-select the camera-authority layer first (fallback: first render-enabled layer).

Returns
  true on success, or false on failure.

Note
  Works only for tile layers.

## ◆ worldToScreen()

bool CRM64Pro::Scene::worldToScreen | ( | float | fWorldX,
|  | float | fWorldY,
|  | float * | fScreenX,
|  | float * | fScreenY,
|  | Sint32 | iLayer = 0 )

Convert world coordinates to screen coordinates.

Parameters

  fWorldX | World X coordinate.
  fWorldY | World Y coordinate.
  fScreenX | Optional output screen X.
  fScreenY | Optional output screen Y.
  iLayer | Layer index (1..getLayerCount()). Use 0 to auto-select the camera-authority layer first (fallback: first render-enabled layer).

Returns
  true on success, or false on failure.

## ◆ mouseToWorld()

bool CRM64Pro::Scene::mouseToWorld | ( | float * | fWorldX,
|  | float * | fWorldY,
|  | Sint32 | iLayer = 0 ) const

Convert current mouse position to world coordinates.

Parameters

  fWorldX | Optional output world X.
  fWorldY | Optional output world Y.
  iLayer | Layer index (1..getLayerCount()). Use 0 to auto-select the camera-authority layer first (fallback: first render-enabled layer).

Returns
  true on success, or false on failure.

## ◆ mouseToCell()

bool CRM64Pro::Scene::mouseToCell | ( | Sint32 * | iCellX,
|  | Sint32 * | iCellY,
|  | Sint32 | iLayer = 0 ) const

Convert current mouse position to tile cell indices.

Parameters

  iCellX | Optional output cell X.
  iCellY | Optional output cell Y.
  iLayer | Layer index (1..getLayerCount()). Use 0 to auto-select the camera-authority layer first (fallback: first render-enabled layer).

Returns
  true on success, or false on failure.

## ◆ update()

Sint32 CRM64Pro::Scene::update | ( | Sint32 | iLayer = 0 | ) |

Update status of the Scene.

Only layers with ::SLF_UPDATE feature are processed. Calculates autoscroll and pre-calculations for rendering. Call as part of logic code. Optionally update individual layers. Calls onUpdateEnd event function at end of each layer update if it exists.

Parameters

  iLayer | Default 0 updates all layers from 1 (background) to foreground. Any other value updates only that layer.

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

Note
  If one or more layer updates fail, the first negative layer error code is returned.

## ◆ render()

Sint32 CRM64Pro::Scene::render | ( | Sint32 | iLayer = 0,
|  | Sint32 | idRes = 0 )

Render the visible layers.

Only layers with ::SLF_RENDER feature are processed. Uses positions from update() to render cells. Call as part of graphic update code. Select rendering order by calling with specific layers. Calls onRenderEnd at end of each layer. With ::SLF_SMOOTHSCROLL, interpolates values for smooth scrolling.

Parameters

  iLayer | Default 0 processes all layers. Values 1 (background) to foreground process only that layer.
  idRes | a valid screen. Default tries the default screen. Does not support rendering to an image.

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

Note
  If one or more layer renders fail, the first negative layer error code is returned.