Particle emitter object class. More...

Detailed Description

Particle emitter object class.

ParticleEmitter controls the full state of a particle effect: emission, simulation, rendering and storage. Objects are owned by ParticleMgr and must be obtained through ParticleMgr::get().

Public Member Functions
bool	info (Sint32 iMode=0) override
	Request ParticleEmitter information.
const string &	getName () const override
	Get the emitter name.
Sint32	getID () const override
	Get the emitter handle.
bool	play ()
	Start or resume particle emission.
bool	pause ()
	Pause particle updates without clearing live particles.
bool	stop ()
	Stop particle updates and emission.
bool	reset ()
	Clear particles and restart the emitter.
bool	clear ()
	Remove all live particles.
Sint32	burst (Sint32 iCount)
	Emit a fixed number of particles immediately.
eGeneralStatus	status () const
	Get current emitter status.
bool	setVisible (bool bVisible)
	Set emitter visibility.
bool	isVisible () const
	Check emitter visibility.
bool	setVisual (eParticleVisual eVisual, Sint32 idRes=0, Sint32 iAnim=-1)
	Set particle visual type and optional image/sprite resource.
bool	setBlendMode (SDL_BlendMode bmValue)
	Set particle blend mode.
bool	setGlowRender (bool bEnabled, float fIntensity=1.0f)
	Enable additive glow rendering for supported particle visuals.
bool	setSpriteAnimation (eParticleSpriteAnimation eMode)
	Set Sprite particle frame selection mode.
bool	setBoundsEnabled (bool bEnabled)
	Enable or disable cached emitter bounds.
bool	setShape (eParticleEmitterShape eShape, float fWidth=0.0f, float fHeight=0.0f)
	Set emitter spawn shape.
bool	setEmissionRate (float fParticlesPerSec)
	Set continuous emission rate.
bool	setEmissionDistance (float fDistance)
	Set movement-distance emission spacing.
bool	setMaxParticles (Sint32 iMaxParticles)
	Set maximum live particle count.
bool	setDuration (float fSeconds)
	Set emission duration in seconds; negative means unlimited.
bool	setLoop (bool bLoop)
	Enable or disable duration looping.
bool	setLifeSpan (float fMinSec, float fMaxSec)
	Set particle lifetime range in seconds.
bool	setDirection (float fAngleDeg, float fSpreadDeg)
	Set emission direction and angular spread in degrees.
bool	setDirectionMode (eParticleDirectionMode eMode)
	Set initial velocity direction mode.
bool	setSpeed (float fMinSpeed, float fMaxSpeed)
	Set particle speed range.
bool	setVelocityLimit (float fMaxSpeed)
	Set the maximum particle velocity magnitude.
bool	setVelocityInheritance (float fAmount)
	Set inherited emitter movement velocity.
bool	setPhysics (float fGravityX, float fGravityY, float fDamping=0.0f)
	Set gravity and damping.
bool	setAttraction (float fStrength, float fRadius=0.0f, float fFalloff=0.0f)
	Set attraction toward emitter center.
bool	setOrbit (float fStrength, float fRadius=0.0f, float fFalloff=0.0f)
	Set orbit force around emitter center.
bool	setCollision (SceneLayerTile *pTileLayer, eParticleCollisionMode eMode=PCM_BOUNCE, float fBounciness=0.5f)
	Set tile-layer collision behavior and runtime layer binding.
bool	setCollisionMode (eParticleCollisionMode eMode, float fBounciness=0.5f)
	Set persistent collision behavior.
bool	setCollisionLayer (SceneLayerTile *pTileLayer)
	Bind the runtime collision tile layer.
bool	setColorKeys (const vector< ParticleColorKey > &vKeys)
	Set color ramp keys.
bool	setTintPalette (const vector< SDL_Color > &vColors)
	Set random tint palette.
const vector< SDL_Color > &	getTintPalette () const
	Get random tint palette.
bool	setScaleRamp (float fStartScale, float fEndScale)
	Set scale interpolation from birth to death.
bool	setScaleKeys (const vector< ParticleScaleKey > &vKeys)
	Set scale ramp keys.
bool	setRotation (float fStartAngle, float fSpinVelocity)
	Set initial angle and spin velocity.
bool	setStretch (float fAmount, bool bAlignToVelocity=true)
	Set stretch amount.
bool	setTurbulence (float fStrength)
	Set random velocity perturbation strength.
bool	setSimulationScale (float fScale)
	Set emitter simulation speed.
bool	setWarmUp (float fSeconds)
	Set fresh-start simulation warm-up time.
bool	setLocalSpace (bool bLocalSpace)
	Select world-space or emitter-local particle movement.
bool	setDrawOrder (eParticleDrawOrder eOrder)
	Set particle rendering order.
bool	setBursts (const vector< ParticleBurst > &vBursts)
	Set timed particle bursts.
bool	setSubEmitters (const vector< ParticleSubEmitter > &vSubEmitters)
	Set particle-triggered sub-emitters.
bool	applyPreset (eParticleEffectPreset ePreset)
	Apply a built-in particle preset.
bool	setPosition (float fX, float fY)
	Set emitter world position.
bool	teleport (float fX, float fY)
	Move the emitter without producing distance emission or inherited movement velocity.
bool	setSeed (Uint32 iSeed)
	Set deterministic random seed.
float	getX () const
	Get emitter X position.
float	getY () const
	Get emitter Y position.
Sint32	getLiveCount () const
	Get current live particle count.
float	getEmissionRate () const
	Get continuous emission rate.
Sint32	getMaxParticles () const
	Get maximum live particle count.
bool	getVisual (eParticleVisual eVisual, Sint32 idRes, Sint32 *iAnim) const
	Get particle visual configuration.
SDL_BlendMode	getBlendMode () const
	Get particle blend mode.
bool	getGlowRender (float *fIntensity=nullptr) const
	Get additive glow rendering configuration.
eParticleSpriteAnimation	getSpriteAnimation () const
	Get Sprite particle frame selection mode.
bool	getBoundsEnabled () const
	Check if cached emitter bounds are enabled.
bool	getBounds (SDL_FRect *pBounds) const
	Get cached emitter bounds.
bool	getShape (eParticleEmitterShape eShape, float fWidth, float *fHeight) const
	Get emitter spawn shape.
float	getEmissionDistance () const
	Get movement-distance emission spacing.
float	getDuration () const
	Get emission duration.
bool	getLoop () const
	Get duration looping mode.
bool	getLifeSpan (float fMinSec, float fMaxSec) const
	Get particle lifetime range.
bool	getDirection (float fAngleDeg, float fSpreadDeg) const
	Get emission direction and spread.
eParticleDirectionMode	getDirectionMode () const
	Get initial velocity direction mode.
bool	getSpeed (float fMinSpeed, float fMaxSpeed) const
	Get particle speed range.
float	getVelocityLimit () const
	Get maximum particle velocity magnitude.
float	getVelocityInheritance () const
	Get inherited emitter movement velocity.
bool	getPhysics (float fGravityX, float fGravityY, float *fDamping) const
	Get gravity and damping configuration.
bool	getAttraction (float fStrength, float fRadius, float *fFalloff) const
	Get attraction configuration.
bool	getOrbit (float fStrength, float fRadius, float *fFalloff) const
	Get orbit configuration.
bool	getCollision (SceneLayerTile *ppTileLayer, eParticleCollisionMode eMode, float *fBounciness) const
	Get collision configuration.
SceneLayerTile *	getCollisionLayer () const
	Get the runtime collision tile layer.
const vector< ParticleColorKey > &	getColorKeys () const
	Get color ramp keys.
const vector< ParticleScaleKey > &	getScaleKeys () const
	Get scale ramp keys.
bool	getRotation (float fStartAngle, float fSpinVelocity) const
	Get initial angle and spin velocity.
bool	getStretch (float fAmount, bool bAlignToVelocity) const
	Get stretch configuration.
float	getTurbulence () const
	Get random velocity perturbation strength.
float	getSimulationScale () const
	Get emitter simulation speed.
float	getWarmUp () const
	Get fresh-start simulation warm-up time.
bool	getLocalSpace () const
	Get local-space simulation mode.
eParticleDrawOrder	getDrawOrder () const
	Get particle rendering order.
const vector< ParticleBurst > &	getBursts () const
	Get timed particle bursts.
const vector< ParticleSubEmitter > &	getSubEmitters () const
	Get particle-triggered sub-emitters.
eParticleEffectPreset	getPreset () const
	Get applied built-in particle preset.
Uint32	getSeed () const
	Get deterministic random seed.
bool	update (float fDeltaTime)
	Advance emitter simulation.
Sint32	render (Sint32 idRes=0)
	Render live particles.
Sint32	save (const string &sCDCFile, const string &sResourceName="")
	Save emitter to a CDC file.
Sint32	save (Sint32 idCDC, const string &sResourceName="")
	Save emitter to an opened CDC archive.

Member Function Documentation

◆ info()

bool CRM64Pro::ParticleEmitter::info ( Sint32 iMode = 0 )

override

Request ParticleEmitter information.

Writes information to the default log.

Parameters

iMode Reserved for future use. Pass 0.

Returns: true on success, or false on failure.

◆ getName()

const string & CRM64Pro::ParticleEmitter::getName ( ) const

override

Get the emitter name.

Returns: Constant reference to the emitter name.

◆ getID()

Sint32 CRM64Pro::ParticleEmitter::getID ( ) const

override

Get the emitter handle.

Returns: ParticleEmitter id managed by ParticleMgr.

◆ play()

bool CRM64Pro::ParticleEmitter::play ( )

Start or resume particle emission.

Returns: true on success, or false on failure.

Note: Existing live particles continue from their current state.

◆ pause()

bool CRM64Pro::ParticleEmitter::pause ( )

Pause particle updates without clearing live particles.

Returns: true on success, or false on failure.

◆ stop()

bool CRM64Pro::ParticleEmitter::stop ( )

Stop particle updates and emission.

Returns: true on success, or false on failure.

Note: Live particles are kept until clear() or reset() is called.

◆ reset()

bool CRM64Pro::ParticleEmitter::reset ( )

Clear particles and restart the emitter.

Returns: true on success, or false on failure.

◆ clear()

bool CRM64Pro::ParticleEmitter::clear ( )

Remove all live particles.

Returns: true on success, or false on failure.

◆ burst()

Sint32 CRM64Pro::ParticleEmitter::burst ( Sint32 iCount )

Emit a fixed number of particles immediately.

Parameters

iCount Number of particles to emit. Must be greater than 0.

Returns: Number of particles emitted on success, or a negative error code on failure.

Note: The emitted amount can be lower than iCount when the configured maximum live particle count is reached.

◆ status()

eGeneralStatus CRM64Pro::ParticleEmitter::status ( ) const

Get current emitter status.

Returns: ::GS_ENABLED while visible and playing, ::GS_HIDDEN while playing with visibility disabled, ::GS_PAUSED while paused, ::GS_DISABLED while stopped or not started, or ::GS_END after finite non-looping emission finishes and all particles expire.

◆ setVisible()

bool CRM64Pro::ParticleEmitter::setVisible ( bool bVisible )

Set emitter visibility.

Parameters

bVisible true to render the emitter, false to skip rendering while still allowing updates.

Returns: true on success, or false on failure.

◆ isVisible()

bool CRM64Pro::ParticleEmitter::isVisible ( ) const

Check emitter visibility.

Returns: true if the emitter is visible, or false if rendering is disabled.

◆ setVisual()

bool CRM64Pro::ParticleEmitter::setVisual	(	eParticleVisual	eVisual,
		Sint32	idRes = 0,
		Sint32	iAnim = -1 )

Set particle visual type and optional image/sprite resource.

Parameters

eVisual	Visual rendering mode. Check ::eParticleVisual for further information.
idRes	Optional Image or Sprite id used by ::PV_IMAGE and ::PV_SPRITE. Use 0 for primitive visual modes.
iAnim	Sprite animation index used by sprite visual modes. Use -1 to keep the Sprite current animation. Default is -1.

Returns: true on success, or false on failure.

Note: The resource handle is borrowed; it is not closed by the emitter. Visual resources loaded through ParticleMgr::load() are owned by the loaded emitter.

◆ setBlendMode()

bool CRM64Pro::ParticleEmitter::setBlendMode ( SDL_BlendMode bmValue )

Set particle blend mode.

Parameters

bmValue SDL blend mode used when rendering particles.

Returns: true on success, or false when bmValue is ::SDL_BLENDMODE_INVALID.

◆ setGlowRender()

bool CRM64Pro::ParticleEmitter::setGlowRender	(	bool	bEnabled,
		float	fIntensity = 1.0f )

Enable additive glow rendering for supported particle visuals.

Parameters

bEnabled	true to render supported visuals through GFX glow helpers, false to use the standard particle renderer.
fIntensity	Glow brightness multiplier clamped to [0.0, 1.0]. Default is 1.0.

Returns: true on success, or false on failure.

Note: Applies to ::PV_SOFT, ::PV_IMAGE and ::PV_SPRITE. Additive ::PV_SOFT particles use the cached GFX glow path even when this setting is disabled.; Image glow rendering is centered. Sprite glow rendering uses the current animation hotspot. Both paths are additive and uniform-scale; particle rotation and stretch are ignored.

◆ setSpriteAnimation()

bool CRM64Pro::ParticleEmitter::setSpriteAnimation ( eParticleSpriteAnimation eMode )

Set Sprite particle frame selection mode.

Parameters

eMode ::PSA_SHARED keeps the current shared-Sprite-frame behavior. ::PSA_RANDOM_OFFSET assigns one random frame offset per particle at spawn.

Returns: true on success, or false when eMode is invalid.

Note: Applies only to ::PV_SPRITE and is persisted in CDC data.

◆ setBoundsEnabled()

bool CRM64Pro::ParticleEmitter::setBoundsEnabled ( bool bEnabled )

Enable or disable cached emitter bounds.

Parameters

bEnabled true to compute bounds during update, false to skip bounds work.

Returns: true on success.

Note: Disabled by default. Bounds are broad-phase world-space AABB data and are not persisted in CDC data.

◆ setShape()

bool CRM64Pro::ParticleEmitter::setShape	(	eParticleEmitterShape	eShape,
		float	fWidth = 0.0f,
		float	fHeight = 0.0f )

Set emitter spawn shape.

Parameters

eShape	Emitter shape. Check ::eParticleEmitterShape for further information.
fWidth	Shape width in pixels in the range [0, 1000000]. Default is 0.
fHeight	Shape height in pixels in the range [0, 1000000]. Used by rectangle and ellipse emitters; ignored by circle and ring emitters. Default is 0.

Returns: true on success, or false on failure.

◆ setEmissionRate()

bool CRM64Pro::ParticleEmitter::setEmissionRate ( float fParticlesPerSec )

Set continuous emission rate.

Parameters

fParticlesPerSec Number of particles emitted per second in the range [0, 1000000]. Use 0 to disable continuous emission.

Returns: true on success, or false on failure.

◆ setEmissionDistance()

bool CRM64Pro::ParticleEmitter::setEmissionDistance ( float fDistance )

Set movement-distance emission spacing.

Parameters

fDistance Distance in pixels between emissions. Use 0 to disable distance emission.

Returns: true on success, or false on failure.

Note: Particles are placed at interpolated points along emitter movement.

◆ setMaxParticles()

bool CRM64Pro::ParticleEmitter::setMaxParticles ( Sint32 iMaxParticles )

Set maximum live particle count.

Parameters

iMaxParticles Maximum live particle count in the range [1, 65536].

Returns: true on success, or false on failure.

Note: Lowering iMaxParticles immediately discards the newest live particles above the new capacity without firing death sub-emitter triggers; new spawns are limited by the new value.

◆ setDuration()

bool CRM64Pro::ParticleEmitter::setDuration ( float fSeconds )

Set emission duration in seconds; negative means unlimited.

Parameters

fSeconds Emission duration in seconds in the range [0, 86400]. Positive values smaller than 1/4096 second are rejected. Use a negative value for unlimited duration.

Returns: true on success, or false on failure.

◆ setLoop()

bool CRM64Pro::ParticleEmitter::setLoop ( bool bLoop )

Enable or disable duration looping.

Parameters

bLoop true to restart duration-limited emission automatically, false to stop at the end.

Returns: true on success, or false on failure.

◆ setLifeSpan()

bool CRM64Pro::ParticleEmitter::setLifeSpan	(	float	fMinSec,
		float	fMaxSec )

Set particle lifetime range in seconds.

Parameters

fMinSec	Minimum particle lifetime in seconds. Must be greater than 0.
fMaxSec	Maximum particle lifetime in seconds. Must be greater than or equal to fMinSec and no greater than 86400.

Returns: true on success, or false on failure.

◆ setDirection()

bool CRM64Pro::ParticleEmitter::setDirection	(	float	fAngleDeg,
		float	fSpreadDeg )

Set emission direction and angular spread in degrees.

Parameters

fAngleDeg	Center direction in degrees.
fSpreadDeg	Random angular spread in degrees around fAngleDeg. Must be greater than or equal to 0.

Returns: true on success, or false on failure.

◆ setDirectionMode()

bool CRM64Pro::ParticleEmitter::setDirectionMode ( eParticleDirectionMode eMode )

Set initial velocity direction mode.

Parameters

eMode Fixed configured direction or radial direction from the emitter center.

Returns: true on success, or false when eMode is invalid.

◆ setSpeed()

bool CRM64Pro::ParticleEmitter::setSpeed	(	float	fMinSpeed,
		float	fMaxSpeed )

Set particle speed range.

Parameters

fMinSpeed	Minimum start speed in pixels per second. Must be greater than or equal to 0.
fMaxSpeed	Maximum start speed in pixels per second. Must be greater than or equal to fMinSpeed.

Returns: true on success, or false on failure.

◆ setVelocityLimit()

bool CRM64Pro::ParticleEmitter::setVelocityLimit ( float fMaxSpeed )

Set the maximum particle velocity magnitude.

Parameters

fMaxSpeed Maximum speed in pixels per second. Use 0 to disable velocity limiting.

Returns: true on success, or false on failure.

◆ setVelocityInheritance()

bool CRM64Pro::ParticleEmitter::setVelocityInheritance ( float fAmount )

Set inherited emitter movement velocity.

Parameters

fAmount Emitter velocity multiplier added to new particles. Must be greater than or equal to 0. Default is 0.

Returns: true on success, or false on failure.

◆ setPhysics()

bool CRM64Pro::ParticleEmitter::setPhysics	(	float	fGravityX,
		float	fGravityY,
		float	fDamping = 0.0f )

Set gravity and damping.

Parameters

fGravityX	Horizontal acceleration in pixels per second squared.
fGravityY	Vertical acceleration in pixels per second squared.
fDamping	Velocity damping factor. Must be greater than or equal to 0. Default is 0.

Returns: true on success, or false on failure.

◆ setAttraction()

bool CRM64Pro::ParticleEmitter::setAttraction	(	float	fStrength,
		float	fRadius = 0.0f,
		float	fFalloff = 0.0f )

Set attraction toward emitter center.

Parameters

fStrength	Attraction strength. Positive values pull particles toward the emitter center; negative values repel.
fRadius	Effective radius in pixels. Use 0 for unlimited radius. Default is 0.
fFalloff	Falloff exponent. Use 0 for no falloff. Default is 0.

Returns: true on success, or false on failure.

◆ setOrbit()

bool CRM64Pro::ParticleEmitter::setOrbit	(	float	fStrength,
		float	fRadius = 0.0f,
		float	fFalloff = 0.0f )

Set orbit force around emitter center.

Parameters

fStrength	Orbit strength. Positive and negative values rotate in opposite directions.
fRadius	Effective radius in pixels. Use 0 for unlimited radius. Default is 0.
fFalloff	Falloff exponent. Use 0 for no falloff. Default is 0.

Returns: true on success, or false on failure.

◆ setCollision()

bool CRM64Pro::ParticleEmitter::setCollision	(	SceneLayerTile *	pTileLayer,
		eParticleCollisionMode	eMode = PCM_BOUNCE,
		float	fBounciness = 0.5f )

Set tile-layer collision behavior and runtime layer binding.

Parameters

pTileLayer	Borrowed Scene tile-layer pointer used for collision checks, or nullptr to leave collision configured but inactive. CRM64Pro does not take ownership. The pointer must remain valid until it is replaced, unbound with setCollisionLayer(nullptr), or this emitter is closed.
eMode	Collision behavior. Check ::eParticleCollisionMode for further information. Default is ::PCM_BOUNCE.
fBounciness	Velocity multiplier used by ::PCM_BOUNCE. Must be greater than or equal to 0. Default is 0.5.

Returns: true on success, or false on failure.

Note: Unbind the layer from every ParticleEmitter before closing the layer or its owning Scene.

◆ setCollisionMode()

bool CRM64Pro::ParticleEmitter::setCollisionMode	(	eParticleCollisionMode	eMode,
		float	fBounciness = 0.5f )

Set persistent collision behavior.

Parameters

eMode	Collision behavior persisted in CDC data. Use ::PCM_NONE to disable collision.
fBounciness	Velocity multiplier used by ::PCM_BOUNCE. Must be greater than or equal to 0. Default is 0.5.

Returns: true on success, or false on invalid input.

Note: Collision is evaluated only while a runtime tile layer is assigned with setCollisionLayer().

◆ setCollisionLayer()

bool CRM64Pro::ParticleEmitter::setCollisionLayer ( SceneLayerTile * pTileLayer )

Bind the runtime collision tile layer.

Parameters

pTileLayer Borrowed Scene tile-layer pointer used for collision checks, or nullptr to unbind it. CRM64Pro does not take ownership. The pointer must remain valid until it is replaced, unbound, or this emitter is closed.

Returns: true on success.

Note: The layer pointer is runtime-only and is not persisted in CDC data.; Unbind the layer from every ParticleEmitter before closing the layer or its owning Scene.

◆ setColorKeys()

bool CRM64Pro::ParticleEmitter::setColorKeys ( const vector< ParticleColorKey > & vKeys )

Set color ramp keys.

Parameters

vKeys Color keys used to interpolate particle color over lifetime. Pass an empty vector to restore the default white ramp.

Returns: true on success, or false on failure.

Note: Key fT values are clamped to [0.0, 1.0] and sorted internally.

◆ setTintPalette()

bool CRM64Pro::ParticleEmitter::setTintPalette ( const vector< SDL_Color > & vColors )

Set random tint palette.

Parameters

vColors Tint colors used for per-particle random color variation. Pass an empty vector to restore the single white default.

Returns: true on success, or false on failure.

Note: One tint is selected at particle spawn and multiplied with the lifetime color ramp. Use a single white color to disable random tinting.

◆ getTintPalette()

const vector< SDL_Color > & CRM64Pro::ParticleEmitter::getTintPalette ( ) const

Get random tint palette.

Returns: Tint colors used for per-particle random color variation.

◆ setScaleRamp()

bool CRM64Pro::ParticleEmitter::setScaleRamp	(	float	fStartScale,
		float	fEndScale )

Set scale interpolation from birth to death.

Parameters

fStartScale	Particle scale at birth in the range [0, 10000]. Zero-scale particles are not rendered.
fEndScale	Particle scale at death in the range [0, 10000]. Zero-scale particles are not rendered.

Returns: true on success, or false on failure.

◆ setScaleKeys()

bool CRM64Pro::ParticleEmitter::setScaleKeys ( const vector< ParticleScaleKey > & vKeys )

Set scale ramp keys.

Parameters

vKeys Scale keys interpolated over particle lifetime. Pass an empty vector to restore the default scale ramp.

Returns: true on success, or false on failure.

Note: Up to eight keys are accepted. Key fT values are clamped to [0.0, 1.0], scales must be in [0, 10000], and keys are sorted internally. Zero-scale particles are not rendered.

◆ setRotation()

bool CRM64Pro::ParticleEmitter::setRotation	(	float	fStartAngle,
		float	fSpinVelocity )

Set initial angle and spin velocity.

Parameters

fStartAngle	Initial render angle in degrees.
fSpinVelocity	Angular velocity in degrees per second.

Returns: true on success, or false on failure.

◆ setStretch()

bool CRM64Pro::ParticleEmitter::setStretch	(	float	fAmount,
		bool	bAlignToVelocity = true )

Set stretch amount.

With bAlignToVelocity enabled, rectangle, line, image and sprite visuals align to the true velocity angle.

Parameters

fAmount	Stretch multiplier. Must be greater than or equal to 0.
bAlignToVelocity	true to align supported visuals to the particle velocity angle. Default is true.

Returns: true on success, or false on failure.

◆ setTurbulence()

bool CRM64Pro::ParticleEmitter::setTurbulence ( float fStrength )

Set random velocity perturbation strength.

Parameters

fStrength Random turbulence strength in pixels per second. Must be greater than or equal to 0.

Returns: true on success, or false on failure.

◆ setSimulationScale()

bool CRM64Pro::ParticleEmitter::setSimulationScale ( float fScale )

Set emitter simulation speed.

Parameters

fScale Simulation time multiplier. Must be greater than or equal to 0. Use 0 to freeze simulation without changing status.

Returns: true on success, or false on failure.

◆ setWarmUp()

bool CRM64Pro::ParticleEmitter::setWarmUp ( float fSeconds )

Set fresh-start simulation warm-up time.

Parameters

fSeconds Particle simulation seconds processed before the first rendered frame, in the range [0.0, 30.0].

Returns: true on success, or false on failure.

Note: Warm-up is applied on play() or reset() only when no live particles exist.

◆ setLocalSpace()

bool CRM64Pro::ParticleEmitter::setLocalSpace ( bool bLocalSpace )

Select world-space or emitter-local particle movement.

Parameters

bLocalSpace true to move existing particles with the emitter, false to leave them in world space.

Returns: true on success, or false on failure.

◆ setDrawOrder()

bool CRM64Pro::ParticleEmitter::setDrawOrder ( eParticleDrawOrder eOrder )

Set particle rendering order.

Parameters

eOrder Storage order or normalized-age sorting mode.

Returns: true on success, or false on failure.

◆ setBursts()

bool CRM64Pro::ParticleEmitter::setBursts ( const vector< ParticleBurst > & vBursts )

Set timed particle bursts.

Parameters

vBursts Timed bursts fired when the emitter timeline crosses each entry. Pass an empty vector to disable timed bursts.

Returns: true on success, or false on failure.

Note: Up to sixteen entries are accepted. Entries are sorted by time internally and repeat with finite looping emitters.

◆ setSubEmitters()

bool CRM64Pro::ParticleEmitter::setSubEmitters ( const vector< ParticleSubEmitter > & vSubEmitters )

Set particle-triggered sub-emitters.

Parameters

vSubEmitters Sub-emitter definitions. Pass an empty vector to disable sub-emission.

Returns: true on success, or false on failure.

Note: Up to eight definitions are accepted. Targets must be finite one-shot built-in presets. Collision triggers fire at most once per particle.; Recursive child spawning is limited to four levels and 256 child events per manager update.; Use ParticleMgr::update() and ParticleMgr::render() so spawned child emitters are advanced and rendered with their parent.

◆ applyPreset()

bool CRM64Pro::ParticleEmitter::applyPreset ( eParticleEffectPreset ePreset )

Apply a built-in particle preset.

Parameters

ePreset Preset identifier. Check ::eParticleEffectPreset for further information.

Returns: true on success, or false on failure.

Note: Presets stop the emitter, clear live particles, reset elapsed emission time and overwrite emitter configuration. Apply the preset first, then adjust custom values.; One-shot presets such as ::PEP_MUZZLE_FLASH, ::PEP_EXPLOSION, ::PEP_SHOCKWAVE, ::PEP_WATER_SPLASH and ::PEP_PICKUP_SPARKLE emit exact configured bursts when played.

◆ setPosition()

bool CRM64Pro::ParticleEmitter::setPosition	(	float	fX,
		float	fY )

Set emitter world position.

Parameters

fX	Horizontal position in pixels in the range [-1000000000, 1000000000].
fY	Vertical position in pixels in the range [-1000000000, 1000000000].

Returns: true on success, or false on failure.

Note: Movement is used by distance emission and emitter velocity inheritance. Use teleport() for discontinuous relocation.

◆ teleport()

bool CRM64Pro::ParticleEmitter::teleport	(	float	fX,
		float	fY )

Move the emitter without producing distance emission or inherited movement velocity.

Parameters

fX	Horizontal destination in pixels.
fY	Vertical destination in pixels.

Returns: true on success, or false on failure.

Note: Local-space particles follow the teleport; world-space particles remain in place.

◆ setSeed()

bool CRM64Pro::ParticleEmitter::setSeed ( Uint32 iSeed )

Set deterministic random seed.

Parameters

iSeed Seed value used by the emitter random generator.

Returns: true on success, or false on failure.

Note: Reusing the same seed and the same update sequence produces deterministic particle spawning across emitter handles and CDC reloads. Fresh play and reset restart the sequence.

◆ getX()

float CRM64Pro::ParticleEmitter::getX ( ) const

Get emitter X position.

Returns: Horizontal emitter position in pixels.

◆ getY()

float CRM64Pro::ParticleEmitter::getY ( ) const

Get emitter Y position.

Returns: Vertical emitter position in pixels.

◆ getLiveCount()

Sint32 CRM64Pro::ParticleEmitter::getLiveCount ( ) const

Get current live particle count.

Returns: Number of live particles currently owned by the emitter.

◆ getEmissionRate()

float CRM64Pro::ParticleEmitter::getEmissionRate ( ) const

Get continuous emission rate.

Returns: Number of particles emitted per second.

◆ getMaxParticles()

Sint32 CRM64Pro::ParticleEmitter::getMaxParticles ( ) const

Get maximum live particle count.

Returns: Configured maximum live particle count.

◆ getVisual()

bool CRM64Pro::ParticleEmitter::getVisual	(	eParticleVisual *	eVisual,
		Sint32 *	idRes,
		Sint32 *	iAnim ) const

Get particle visual configuration.

Parameters

eVisual	Output particle visual mode.
idRes	Output Image or Sprite resource id.
iAnim	Output sprite animation index.

Returns: true on success, or false on failure.

◆ getBlendMode()

SDL_BlendMode CRM64Pro::ParticleEmitter::getBlendMode ( ) const

Get particle blend mode.

Returns: SDL blend mode used when rendering particles.

◆ getGlowRender()

bool CRM64Pro::ParticleEmitter::getGlowRender ( float * fIntensity = nullptr ) const

Get additive glow rendering configuration.

Parameters

fIntensity Optional output glow brightness multiplier.

Returns: true when glow rendering is enabled, or false when disabled.

◆ getSpriteAnimation()

eParticleSpriteAnimation CRM64Pro::ParticleEmitter::getSpriteAnimation ( ) const

Get Sprite particle frame selection mode.

Returns: Sprite particle frame selection mode.

◆ getBoundsEnabled()

bool CRM64Pro::ParticleEmitter::getBoundsEnabled ( ) const

Check if cached emitter bounds are enabled.

Returns: true when bounds are computed during update, or false otherwise.

◆ getBounds()

bool CRM64Pro::ParticleEmitter::getBounds ( SDL_FRect * pBounds ) const

Get cached emitter bounds.

Parameters

pBounds Output world-space AABB covering live renderable particles.

Returns: true when bounds are enabled and valid, or false when disabled, empty or not yet updated.

Note: The returned rectangle is conservative broad-phase data, not pixel-perfect collision. It is updated by update().

◆ getShape()

bool CRM64Pro::ParticleEmitter::getShape	(	eParticleEmitterShape *	eShape,
		float *	fWidth,
		float *	fHeight ) const

Get emitter spawn shape.

Parameters

eShape	Output emitter shape.
fWidth	Output shape width in pixels.
fHeight	Output shape height in pixels.

Returns: true on success, or false on failure.

◆ getEmissionDistance()

float CRM64Pro::ParticleEmitter::getEmissionDistance ( ) const

Get movement-distance emission spacing.

Returns: Distance in pixels between emissions, or 0 when disabled.

◆ getDuration()

float CRM64Pro::ParticleEmitter::getDuration ( ) const

Get emission duration.

Returns: Emission duration in seconds, or -1 for unlimited duration.

◆ getLoop()

bool CRM64Pro::ParticleEmitter::getLoop ( ) const

Get duration looping mode.

Returns: true when duration-limited emission loops, or false otherwise.

◆ getLifeSpan()

bool CRM64Pro::ParticleEmitter::getLifeSpan	(	float *	fMinSec,
		float *	fMaxSec ) const

Get particle lifetime range.

Parameters

fMinSec	Output minimum particle lifetime in seconds.
fMaxSec	Output maximum particle lifetime in seconds.

Returns: true on success, or false on failure.

◆ getDirection()

bool CRM64Pro::ParticleEmitter::getDirection	(	float *	fAngleDeg,
		float *	fSpreadDeg ) const

Get emission direction and spread.

Parameters

fAngleDeg	Output center direction in degrees.
fSpreadDeg	Output angular spread in degrees.

Returns: true on success, or false on failure.

◆ getDirectionMode()

eParticleDirectionMode CRM64Pro::ParticleEmitter::getDirectionMode ( ) const

Get initial velocity direction mode.

Returns: Configured fixed or radial direction mode.

◆ getSpeed()

bool CRM64Pro::ParticleEmitter::getSpeed	(	float *	fMinSpeed,
		float *	fMaxSpeed ) const

Get particle speed range.

Parameters

fMinSpeed	Output minimum start speed in pixels per second.
fMaxSpeed	Output maximum start speed in pixels per second.

Returns: true on success, or false on failure.

◆ getVelocityLimit()

float CRM64Pro::ParticleEmitter::getVelocityLimit ( ) const

Get maximum particle velocity magnitude.

Returns: Maximum speed in pixels per second, or 0 when disabled.

◆ getVelocityInheritance()

float CRM64Pro::ParticleEmitter::getVelocityInheritance ( ) const

Get inherited emitter movement velocity.

Returns: Emitter velocity multiplier applied to new particles.

◆ getPhysics()

bool CRM64Pro::ParticleEmitter::getPhysics	(	float *	fGravityX,
		float *	fGravityY,
		float *	fDamping ) const

Get gravity and damping configuration.

Parameters

fGravityX	Output horizontal acceleration.
fGravityY	Output vertical acceleration.
fDamping	Output velocity damping factor.

Returns: true on success, or false on failure.

◆ getAttraction()

bool CRM64Pro::ParticleEmitter::getAttraction	(	float *	fStrength,
		float *	fRadius,
		float *	fFalloff ) const

Get attraction configuration.

Parameters

fStrength	Output attraction strength.
fRadius	Output effective radius in pixels.
fFalloff	Output falloff exponent.

Returns: true on success, or false on failure.

◆ getOrbit()

bool CRM64Pro::ParticleEmitter::getOrbit	(	float *	fStrength,
		float *	fRadius,
		float *	fFalloff ) const

Get orbit configuration.

Parameters

fStrength	Output orbit strength.
fRadius	Output effective radius in pixels.
fFalloff	Output falloff exponent.

Returns: true on success, or false on failure.

◆ getCollision()

bool CRM64Pro::ParticleEmitter::getCollision	(	SceneLayerTile **	ppTileLayer,
		eParticleCollisionMode *	eMode,
		float *	fBounciness ) const

Get collision configuration.

Parameters

ppTileLayer	Optional output that receives the borrowed collision tile-layer pointer. CRM64Pro retains ownership; the caller must not delete it. The pointer remains valid until it is replaced, unbound, or the layer or emitter is closed.
eMode	Output collision behavior.
fBounciness	Output bounce velocity multiplier.

Returns: true on success, or false on failure.

◆ getCollisionLayer()

SceneLayerTile * CRM64Pro::ParticleEmitter::getCollisionLayer ( ) const

Get the runtime collision tile layer.

Returns: Borrowed runtime tile-layer pointer, or nullptr when no layer is bound.

Note: The returned pointer must not be deleted. It remains valid until it is replaced, unbound, or the layer or emitter is closed.

◆ getColorKeys()

const vector< ParticleColorKey > & CRM64Pro::ParticleEmitter::getColorKeys ( ) const

Get color ramp keys.

Returns: Color keys used to interpolate particle color over lifetime.

◆ getScaleKeys()

const vector< ParticleScaleKey > & CRM64Pro::ParticleEmitter::getScaleKeys ( ) const

Get scale ramp keys.

Returns: Scale keys used to interpolate particle scale over lifetime.

◆ getRotation()

bool CRM64Pro::ParticleEmitter::getRotation	(	float *	fStartAngle,
		float *	fSpinVelocity ) const

Get initial angle and spin velocity.

Parameters

fStartAngle	Output initial render angle in degrees.
fSpinVelocity	Output angular velocity in degrees per second.

Returns: true on success, or false on failure.

◆ getStretch()

bool CRM64Pro::ParticleEmitter::getStretch	(	float *	fAmount,
		bool *	bAlignToVelocity ) const

Get stretch configuration.

Parameters

fAmount	Output stretch multiplier.
bAlignToVelocity	Output velocity-alignment mode.

Returns: true on success, or false on failure.

◆ getTurbulence()

float CRM64Pro::ParticleEmitter::getTurbulence ( ) const

Get random velocity perturbation strength.

Returns: Turbulence strength in pixels per second.

◆ getSimulationScale()

float CRM64Pro::ParticleEmitter::getSimulationScale ( ) const

Get emitter simulation speed.

Returns: Simulation time multiplier.

◆ getWarmUp()

float CRM64Pro::ParticleEmitter::getWarmUp ( ) const

Get fresh-start simulation warm-up time.

Returns: Warm-up duration in seconds.

◆ getLocalSpace()

bool CRM64Pro::ParticleEmitter::getLocalSpace ( ) const

Get local-space simulation mode.

Returns: true for emitter-local movement, or false for world-space movement.

◆ getDrawOrder()

eParticleDrawOrder CRM64Pro::ParticleEmitter::getDrawOrder ( ) const

Get particle rendering order.

Returns: Configured particle rendering order.

◆ getBursts()

const vector< ParticleBurst > & CRM64Pro::ParticleEmitter::getBursts ( ) const

Get timed particle bursts.

Returns: Timed burst definitions.

◆ getSubEmitters()

const vector< ParticleSubEmitter > & CRM64Pro::ParticleEmitter::getSubEmitters ( ) const

Get particle-triggered sub-emitters.

Returns: Particle sub-emitter definitions.

◆ getPreset()

eParticleEffectPreset CRM64Pro::ParticleEmitter::getPreset ( ) const

Get applied built-in particle preset.

Returns: Last applied or loaded preset identifier.

◆ getSeed()

Uint32 CRM64Pro::ParticleEmitter::getSeed ( ) const

Get deterministic random seed.

Returns: Seed used by the emitter random generator.

◆ update()

bool CRM64Pro::ParticleEmitter::update ( float fDeltaTime )

Advance emitter simulation.

Parameters

fDeltaTime Elapsed time in seconds in the range [0, 1]. The scaled delta must also be no greater than 1.

Returns: true on success, or false on failure.

Note: Use Main::getLogicDeltaTime() for fixed-step simulation.; Returns false when more than 8192 emission timestamps are generated in one update.

◆ render()

Sint32 CRM64Pro::ParticleEmitter::render ( Sint32 idRes = 0 )

Render live particles.

Parameters

idRes Render target id. Use 0 for the default screen target.

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

Note: Pixel, rectangle, line and non-glow soft rendering to an Image target supports standard alpha blending. Other blend modes for those paths require a Screen target and return an unsupported-operation error.; Image and Sprite visuals are scaled but not rotated when rendering to an Image target.

◆ save() [1/2]

Sint32 CRM64Pro::ParticleEmitter::save	(	const string &	sCDCFile,
		const string &	sResourceName = "" )

Save emitter to a CDC file.

Parameters

sCDCFile	string containing the [directory]+filename.
sResourceName	Optional resource name inside the CDC archive. When empty, the emitter name is used.

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

◆ save() [2/2]

Sint32 CRM64Pro::ParticleEmitter::save	(	Sint32	idCDC,
		const string &	sResourceName = "" )

Save emitter to an opened CDC archive.

Parameters

idCDC	CDC id.
sResourceName	Optional resource name inside the CDC archive. When empty, the emitter name is used.

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

Detailed Description

Public Member Functions

Member Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ play()

◆ pause()

◆ stop()

◆ reset()

◆ clear()

◆ burst()

◆ status()

◆ setVisible()

◆ isVisible()

◆ setVisual()

◆ setBlendMode()

◆ setGlowRender()

◆ setSpriteAnimation()

◆ setBoundsEnabled()

◆ setShape()

◆ setEmissionRate()

◆ setEmissionDistance()

◆ setMaxParticles()

◆ setDuration()

◆ setLoop()

◆ setLifeSpan()

◆ setDirection()

◆ setDirectionMode()

◆ setSpeed()

◆ setVelocityLimit()

◆ setVelocityInheritance()

◆ setPhysics()

◆ setAttraction()

◆ setOrbit()

◆ setCollision()

◆ setCollisionMode()

◆ setCollisionLayer()

◆ setColorKeys()

◆ setTintPalette()

◆ getTintPalette()

◆ setScaleRamp()

◆ setScaleKeys()

◆ setRotation()

◆ setStretch()

◆ setTurbulence()

◆ setSimulationScale()

◆ setWarmUp()

◆ setLocalSpace()

◆ setDrawOrder()

◆ setBursts()

◆ setSubEmitters()

◆ applyPreset()

◆ setPosition()

◆ teleport()

◆ setSeed()

◆ getX()

◆ getY()

◆ getLiveCount()

◆ getEmissionRate()

◆ getMaxParticles()

◆ getVisual()

◆ getBlendMode()

◆ getGlowRender()

◆ getSpriteAnimation()

◆ getBoundsEnabled()

◆ getBounds()

◆ getShape()

◆ getEmissionDistance()

◆ getDuration()

◆ getLoop()

◆ getLifeSpan()

◆ getDirection()

◆ getDirectionMode()

◆ getSpeed()

◆ getVelocityLimit()

◆ getVelocityInheritance()

◆ getPhysics()

◆ getAttraction()

◆ getOrbit()