particle_system.h

Go to the documentation of this file.

/*
 * Copyright 2011-2025 Branimir Karadzic. All rights reserved.
 * License: https://github.com/bkaradzic/bgfx/blob/master/LICENSE
 */
 
#ifndef PARTICLE_SYSTEM_H_HEADER_GUARD
#define PARTICLE_SYSTEM_H_HEADER_GUARD
 
#include <bx/allocator.h>
#include <bx/bounds.h>
#include <bx/easing.h>
#include <bx/rng.h>
#include <bgfx/bgfx.h>
#include <math/gradient.h>
#include <math/math.h>
#include <math/bbox.h>
#include <core/base/basetypes.hpp>
 
struct EmitterHandle { uint16_t idx; };
 
template<typename Ty>
inline bool isValid(Ty _handle)
{
    return _handle.idx != UINT16_MAX;
}
 
struct EmitterShape
{
    enum Enum
    {
        Sphere,
        Hemisphere,
        Circle,
        Box,
        Rect,
 
        Count
    };
};
 
struct EmitterDirection
{
    enum Enum
    {
        Up,
        Outward,
 
        Count
    };
};
 
struct SimulationSpace
{
    enum Enum
    {
        World, // Particles are simulated in world space (current behavior)
        Local, // Particles are simulated in local space and transformed during rendering
 
        Count
    };
};
 
struct EmitterUniforms
{
    void reset();
 
    // Simulation space determines how particles are transformed
    SimulationSpace::Enum m_simulationSpace;
    
    // Transform for both local and world simulation
    // Using math::transform for better performance - keeps components separate and combines into matrix when needed
    math::transform m_transform;
    math::transform m_prevTransform; // Previous transform for motion interpolation (set internally)
 
    // Emission shape scale (separate from transform scale for flexibility)
    math::vec3 m_emissionShapeScale; // 3D scale for the emission shape (x, y, z)
 
    math::gradient<frange_t> m_velocityGradient; // Velocity gradient over particle lifetime
    math::gradient<frange_t> m_blendGradient;    // Blend/opacity gradient over particle lifetime
    math::gradient<frange_t> m_scaleGradient;    // Scale gradient over particle lifetime
    float m_lifetime;
    float m_gravityScale;
    float m_particlesPerSecond; // Emission rate in particles per second
    float m_temporalMotion; // Temporal motion interpolation factor (0.0 = no interpolation, 1.0 = full interpolation)
    float m_velocityDamping; // Velocity damping factor (0.0 = no damping, 1.0 = full damping)
    math::vec3 m_forceOverLifetime; // Additional force applied over particle lifetime
    frange_t m_sizeBySpeedRange; // Size multiplier range [min_multiplier, max_multiplier]
    frange_t m_sizeBySpeedVelocityRange; // Velocity range for size mapping [min_speed, max_speed]
    math::gradient<math::color> m_colorBySpeedGradient; // Color gradient based on speed
    frange_t m_colorBySpeedVelocityRange; // Velocity range for color mapping [min_speed, max_speed]
 
    math::gradient<float> m_lifetimeByEmitterSpeedGradient; // Lifetime multiplier gradient based on emitter speed
    frange_t m_lifetimeByEmitterSpeedRange; // Emitter speed range for lifetime mapping [min_speed, max_speed]
 
    math::gradient<math::color> m_colorGradient; // Color gradient over particle lifetime
    float m_emissionLifetime; // Duration of one emission cycle
    float m_blendMultiplier; // Global blend multiplier for all particles (0.0 = fully transparent, 1.0 = no change)
 
    // Playback control states
    bool m_playing; // Whether the emitter is currently playing/active
    bool m_paused;  // Whether the emitter is paused (playing but with dt = 0)
    bool m_loop;    // Whether the emitter loops continuously (true) or emits only once (false)
 
    bx::Easing::Enum m_easePos; // Only position easing remains - others handled by gradients
 
    bgfx::TextureHandle m_texture;
};
 
void psInit(uint16_t _maxEmitters = 64, bx::AllocatorI* _allocator = nullptr);
 
void psShutdown();
 
// Note: Sprite system removed - use bgfx::TextureHandle directly in EmitterUniforms
 
EmitterHandle psCreateEmitter(EmitterShape::Enum _shape, EmitterDirection::Enum _direction, uint32_t _maxParticles);
 
void psUpdateEmitter(EmitterHandle _handle, float _dt, EmitterUniforms* _uniforms = nullptr);
 
bool psHasUpdated(EmitterHandle _handle);
 
void psResetEmitter(EmitterHandle _handle);
 
void psGetAabb(EmitterHandle _handle, math::bbox& _outAabb);
 
uint32_t psGetNumParticles(EmitterHandle _handle);
 
void psDestroyEmitter(EmitterHandle _handle);
 
void psRenderEmitter(EmitterHandle _handle, uint8_t _view, bgfx::ProgramHandle _program, const float* _mtxView, const math::vec3& _eye, bgfx::TextureHandle _texture);
 
uint32_t psRenderEmitterBatch(const EmitterHandle* _handles, uint32_t _count, uint8_t _view, bgfx::ProgramHandle _program, const float* _mtxView, const math::vec3& _eye, bgfx::TextureHandle _texture);
 
#endif // PARTICLE_SYSTEM_H_HEADER_GUARD