Description

Scene runtime for layered 2D worlds.

Scene owns layers, camera transforms and world state. Applications advance it with update() and draw it with render() from their main-thread game loop.

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.
void	CRM64Pro::Scene::setLightingAmbient (Uint32 iColor)
	Set the ambient color used by the optional Scene lighting pass.
Uint32	CRM64Pro::Scene::getLightingAmbient () const
	Get the ambient color used by the optional Scene lighting pass.
void	CRM64Pro::Scene::setLightingAmbientIntensity (float fIntensity)
	Set the ambient intensity used by the optional Scene lighting pass.
float	CRM64Pro::Scene::getLightingAmbientIntensity () const
	Get the ambient intensity used by the optional Scene lighting pass.
void	CRM64Pro::Scene::setLightingEnabled (bool bEnabled)
	Enable or disable interpretation and rendering of C64Light and light-occluder objects.
bool	CRM64Pro::Scene::isLightingEnabled () const
	Check whether Scene lighting interpretation and rendering is enabled.
void	CRM64Pro::Scene::setEffectsEnabled (bool bEnabled)
	Enable or disable Scene effects.
bool	CRM64Pro::Scene::isEffectsEnabled () const
	Check whether Scene effects are enabled.
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.
void	CRM64Pro::Scene::setOnParticleCollisionEvent (ParticleCollisionEventCallback fnCallback)
	Set the global batched particle collision 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 Scene or layer debug overlays.
bool	CRM64Pro::Scene::isDebugOverlayEnabled (eSceneDebugOverlay eFlags) const
	Check whether all requested Scene or layer debug overlays are enabled.
bool	CRM64Pro::Scene::setDebugObjectOverlay (eSceneDebugOverlay eOverlays, eSceneDebugObjectType eTypes, bool bEnable)
	Enable or disable object visualizations for selected object categories.
bool	CRM64Pro::Scene::isDebugObjectOverlayEnabled (eSceneDebugOverlay eOverlays, eSceneDebugObjectType eTypes) const
	Check whether object visualizations are enabled for selected object categories.
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	Descriptive layer name. It may be empty, the numeric layer ID is used for identity and access.
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)

◆ setLightingAmbient()

void CRM64Pro::Scene::setLightingAmbient ( Uint32 iColor )

Set the ambient color used by the optional Scene lighting pass.

The color defines the ambient tint and is multiplied by getLightingAmbientIntensity() before the lightmap is rendered.

Parameters

iColor Ambient color in 0xRRGGBBAA format. Alpha is stored but does not affect the current MOD composite.

Note: White leaves scene pixels unchanged only when ambient intensity is 1.0.; Scene::save() exports this value as the TMX property c64scn_lighting_ambient.

◆ getLightingAmbient()

Uint32 CRM64Pro::Scene::getLightingAmbient ( ) const

Get the ambient color used by the optional Scene lighting pass.

Returns: Ambient color in 0xRRGGBBAA format.

◆ setLightingAmbientIntensity()

void CRM64Pro::Scene::setLightingAmbientIntensity ( float fIntensity )

Set the ambient intensity used by the optional Scene lighting pass.

Parameters

fIntensity Ambient intensity. Finite values are clamped to [0.0, 1.0]; non-finite values are ignored.

Note: The default is 1.0. Values below 1.0 leave lightmap headroom for local lights.; Scene::save() exports this value as the TMX property c64scn_lighting_ambient_intensity.

◆ getLightingAmbientIntensity()

float CRM64Pro::Scene::getLightingAmbientIntensity ( ) const

Get the ambient intensity used by the optional Scene lighting pass.

Returns: Ambient intensity in the [0.0, 1.0] range.

◆ setLightingEnabled()

void CRM64Pro::Scene::setLightingEnabled ( bool bEnabled )

Enable or disable interpretation and rendering of C64Light and light-occluder objects.

Parameters

bEnabled true to enable Scene lighting, or false to disable it. Lighting is disabled by default. Full-intensity white ambient skips the lighting pass because it cannot affect the current LDR lightmap.

Note: Scene::save() exports this value as the TMX property c64scn_lighting_enabled.

◆ isLightingEnabled()

bool CRM64Pro::Scene::isLightingEnabled ( ) const

Check whether Scene lighting interpretation and rendering is enabled.

Returns: true when enabled, or false otherwise.

◆ setEffectsEnabled()

void CRM64Pro::Scene::setEffectsEnabled ( bool bEnabled )

Enable or disable Scene effects.

Parameters

bEnabled true to enable Scene effects, or false to disable them. Effects are disabled by default. Disabling effects pauses and hides C64Particle scene objects.

Note: Scene::save() exports this value as the TMX property c64scn_effects_enabled.

◆ isEffectsEnabled()

bool CRM64Pro::Scene::isEffectsEnabled ( ) const

Check whether Scene effects are enabled.

Returns: true when enabled, or false otherwise.

◆ 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. Non-repeating tile layers are clamped to their map bounds. Image and object layers accept unrestricted manual positions to support parallax and unbounded worlds.

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.; Position helpers resolve against the layer's total size. On a zero-sized object-layer axis, ::PH_CENTER centers the world origin and ::PH_RIGHT/::PH_BOTTOM align it to the viewport end.; 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.

◆ setOnParticleCollisionEvent()

void CRM64Pro::Scene::setOnParticleCollisionEvent ( ParticleCollisionEventCallback fnCallback )

Set the global batched particle collision callback.

Registering a callback enables collision-hit collection for Scene-owned particle emitters. Events are dispatched after particle simulation, outside object-layer locks, once per emitter and target object during each update. Clearing the callback disables collection overhead. Tile-layer collisions do not generate this object-target event.

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 Scene or layer debug overlays.

Object overlay flags are rejected and must be configured with setDebugObjectOverlay().

Parameters

eFlags	Combination of SDO_TILE_CELLGRID and SDO_CAMERA_DEADZONE.
bEnable	true to enable, false to disable.

Returns: true on success, or false when eFlags contains an object or unknown flag.

◆ isDebugOverlayEnabled()

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

Check whether all requested Scene or layer debug overlays are enabled.

Parameters

eFlags Combination of SDO_TILE_CELLGRID and SDO_CAMERA_DEADZONE.

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

◆ setDebugObjectOverlay()

bool CRM64Pro::Scene::setDebugObjectOverlay	(	eSceneDebugOverlay	eOverlays,
		eSceneDebugObjectType	eTypes,
		bool	bEnable )

Enable or disable object visualizations for selected object categories.

Each object visualization keeps its own category mask, allowing combinations such as names for every object category and AABBs only for lights. Scene and layer flags are rejected.

Parameters

eOverlays	Combination of SDO_OBJECT_AABB, SDO_OBJECT_SHAPE, SDO_OBJECT_NAME and SDO_TRIGGER_ZONES.
eTypes	Object category or combination of categories affected by this operation.
bEnable	true to enable the selected category associations, false to disable them.

Returns: true on success, or false when either mask is empty or contains an unsupported flag.

◆ isDebugObjectOverlayEnabled()

bool CRM64Pro::Scene::isDebugObjectOverlayEnabled	(	eSceneDebugOverlay	eOverlays,
		eSceneDebugObjectType	eTypes ) const

Check whether object visualizations are enabled for selected object categories.

Parameters

eOverlays	Combination of object visualization flags.
eTypes	Object category or combination of categories to check.

Returns: true when every requested visualization/category association is enabled; empty or invalid masks return false.

◆ setDebugOverlayColor()

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

Set debug overlay color for a specific overlay flag.

Shape colors use each object's c64scn_shape_color property and names use the built-in debug font.

Parameters

eFlag	Single color-configurable overlay flag (SDO_OBJECT_AABB, SDO_TILE_CELLGRID, SDO_TRIGGER_ZONES or 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: This is a main-thread operation. It must not overlap render() or another update() call on the same Scene.; Any internal worker tasks must complete before this method returns.; 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: This is a main-thread operation. It must not overlap update() or another render() call on the same Scene.; Automatic Scene lighting is applied only when iLayer is 0. Rendering an individual layer does not apply the Scene lightmap.; If one or more layer renders fail, the first negative layer error code is returned.

Description

Classes

Functions

Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ getWidth()

◆ getHeight()

◆ getLayerCount()

◆ createLayer()

◆ addLayer()

◆ closeLayer()

◆ clear()

◆ setViewport()

◆ getViewport()

◆ setBackgroundColor()

◆ getBackgroundColor()

◆ setLightingAmbient()

◆ getLightingAmbient()

◆ setLightingAmbientIntensity()

◆ getLightingAmbientIntensity()

◆ setLightingEnabled()

◆ isLightingEnabled()

◆ setEffectsEnabled()

◆ isEffectsEnabled()

◆ getModificationDate()

◆ getCreationDate()

◆ setLayerFeatures()

◆ getLayerFeatures()

◆ pause()

◆ resume()

◆ setLayerAlphaMod()

◆ getLayerAlphaMod()

◆ setLayerParallaxRatio()

◆ getLayerParallaxRatio()

◆ setCameraMode()

◆ getCameraMode()

◆ setCameraParams()

◆ getCameraParams()

◆ setCameraTarget() [1/2]

◆ setCameraTarget() [2/2]

◆ clearCameraTarget()

◆ setCameraPosition()

◆ setCameraBounds()

◆ getCameraBounds()

◆ setCameraOffsetCallback()

◆ setCameraShake()

◆ clearCameraShake()

◆ setLayerPosition()

◆ getLayerPosition()

◆ getLayerType()

◆ accessLayerTile()

◆ accessLayerObject()

◆ accessLayerImage()

◆ setLayerOnUpdateEnd()

◆ getLayerOnUpdateEnd()

◆ setLayerOnRenderEnd()

◆ getLayerOnRenderEnd()

◆ setOnTriggerEvent()

◆ setOnParticleCollisionEvent()

◆ getLayerName()

◆ setLayerName()

◆ setDebugOverlay()

◆ isDebugOverlayEnabled()

◆ setDebugObjectOverlay()

◆ isDebugObjectOverlayEnabled()

◆ setDebugOverlayColor()

◆ getDebugOverlayColor()

◆ screenToWorld()

◆ screenToCell()

◆ worldToScreen()

◆ mouseToWorld()

◆ mouseToCell()

◆ update()

◆ render()