Introduction

Since the Particle emitter spawns the IOS and the IOFx actors, most programmer interaction with this module focuses on the rendering side of the IOFX actors and RenderVolumes.

IOFX Semantics and Render Layouts

IOFX can output different render semantics (defined in IofxRenderSemantic enum):

POSITION     - 3D Position of particle
COLOR        - Color of particle
VELOCITY     - 3D Linear velocity of particle
SCALE        - 2D or 3D Scale of particle
LIFE_REMAIN  - Normalized life of particle = 1.0 (spawned) -> 0.0 (dead)
DENSITY      - Particle density
SUBTEXTURE   - Sub-texture index of particle (only Sprites)
ORIENTATION  - Particle screen orientation = angle in radians (CCW in screen plane, only Sprites)
ROTATION     - 3D particle rotation (only Meshes)
USER_DATA    - User data - 32 bits (passed from APEX Emitter)

Each IOS actor operates in either mesh or sprite mode, meaning all of the IOFX assets used with a single IOS actor will either all be mesh IOFX or sprite IOFX. This detail is not exposed to the artist. APEX simply creates two IOS actors if the one IOS asset is used with both sprite and mesh IOFX assets.

The IOS actor will create sprite buffers if it is operating in sprite mode, or mesh instance buffers if it is operating in mesh mode. Mesh instance buffers will have fixed semantics; POSITION, ROTATION, SCALE, VELOCITY, LIFE_REMAIN, and DENSITY if the underlying IOS supplies a density value (currently only 3.x Particle IOSes with SPH enabled, or BasicIOS or 3.x ParticleIOS when grid density is enabled).

Sprite buffers will have semantics for the sum of all IOFX assets currently in use with an IOS actor. This means the semantics output by an IOS actor may change as emitters are added to or removed from a scene. The next time the IOFX actors of that IOS are updated by the render thread, the old sprite buffers will be released and new sprite buffers will be allocated with the new semantics. No rendering data is lost for any frames because the simulation output buffer always has the correct semantics.

Sprite/Mesh render buffer represents an array of structures, like ordinary Vertex buffer in Computer Graphics. Each structure of render buffer is defined by render layout (corresponding to Vertex Declaration in Computer Graphics), consisting of set {semantic, format, offset} and stride.

All available Sprite semantics & format pairs are defined in IofxSpriteRenderLayoutElement enum:

POSITION_FLOAT3
COLOR_RGBA8
COLOR_BGRA8
COLOR_FLOAT4
VELOCITY_FLOAT3
SCALE_FLOAT2
LIFE_REMAIN_FLOAT1
DENSITY_FLOAT1
SUBTEXTURE_FLOAT1
ORIENTATION_FLOAT1
USER_DATA_UINT1

All available Mesh semantics & format pairs are defined in IofxMeshRenderLayoutElement enum:

POSITION_FLOAT3
ROTATION_SCALE_FLOAT3x3
POSE_FLOAT3x4
VELOCITY_LIFE_FLOAT4
DENSITY_FLOAT1
COLOR_RGBA8
COLOR_BGRA8
COLOR_FLOAT4
USER_DATA_UINT1

Render layout for Sprite/Mesh render buffer is defined in IofxSpriteRenderLayout/IofxMeshRenderLayout. It has offsets array indexed by layout element, which encodes render buffer structure: if offset value is -1 the corresponding layout element is not present, otherwise it’s present in the structure at the provided offset. Stride in render layout sets the whole size of the render buffer structure, and should be enough to store all presented layout elements with corresponding offsets.

Sprite render layout also supports render from surfaces. In this case IofxSpriteRenderLayout::surfaceCount value is greater than zero and IofxSpriteRenderLayout::surfaceDescs array describes surfaces and IofxSpriteRenderLayout::surfaceElements array defines layout for each surface.

All available Sprite surface layouts are defined in IofxSpriteRenderLayoutSurfaceElement enum:

POSITION_FLOAT4
SCALE_ORIENT_SUBTEX_FLOAT4
COLOR_RGBA8
COLOR_BGRA8
COLOR_FLOAT4

By default APEX creates Sprite/Mesh render layout based on the current set of semantics, so that all output semantics are presented in the render buffer. User can create its own render layout by implementing IofxRenderCallback and overriding getIofxSpriteRenderLayout and getIofxMeshRenderLayout methods:

class IofxRenderCallbackImpl : public IofxRenderCallback
{
    virtual bool getIofxSpriteRenderLayout(IofxSpriteRenderLayout& spriteRenderLayout, uint32_t spriteCount, uint32_t spriteSemanticsBitmap, RenderInteropFlags::Enum interopFlags)
    {
        //fill spriteRenderLayout here
        return true;
    }
    virtual bool getIofxMeshRenderLayout(IofxMeshRenderLayout& meshRenderLayout, uint32_t meshCount, uint32_t meshSemanticsBitmap, RenderInteropFlags::Enum interopFlags)
    {
        //fill meshRenderLayout here
        return true;
    }
};

Argument spriteCount/meshCount determines the 1D size of render buffer or 2D size of render surfaces. Surface width should be power of two and >= 32. It is a good idea to determine surface width as a square root of spriteCount ceiled to the nearest power of two. Non-zero bits in the spriteSemanticsBitmap/meshSemanticsBitmap argument correspond to the semantics defined in the IofxRenderSemantic enum and describe which semantics are presented in IOFX output. User are free to provide any set of layout elements in the render layout, even if the corresponding semantics are not present in IOFX output, in this case IOFX outputs default values for these semantics. The most common case is to create just one or a few fixed render layout(s) matching user particles shader(s) input.

Renderables

Rendering is implemented using IOFX Renderable object. Each IOFX actor has its own IOFX Renderable which stores all needed rendering information and can live after the original IOFX actor has been released. Before accessing rendering data in IOFX Renderables, it should be updated once for each rendering frame by calling ModuleIofx::prepareRenderables(const Scene&). IOFX module has method ModuleIofx::createIofxRenderableIterator(const Scene&) to create iterator over all IOFX renderables. The following code snipper illustrates how to use it all together:

mIofxModule->prepareRenderables(*mApexScene);
IofxRenderableIterator* iter = mIofxModule->createIofxRenderableIterator(*mApexScene);
for (IofxRenderable* renderable = iter->getFirst(); renderable ; renderable = iter->getNext())
{
    if (visibilityCheck(renderable->getBounds())
    {
        if (const IofxSpriteRenderData* spriteRenderData = renderable->getSpriteRenderData())
        {
            renderSprites(spriteRenderData);
        }
        else
        if (const IofxMeshRenderData* meshRenderData = renderable->getMeshRenderData())
        {
            renderMeshes(meshRenderData);
        }
    }
    renderable->release();
}
iter->release();

There are two kinds of render data in IOFX Renderable, one is unique per Renderable and other is shared across several Renderables. IofxSpriteRenderData has references to shared IofxSpriteSharedRenderData, and IofxMeshRenderData has references to shared IofxMeshSharedRenderData.

Shared render data stores Sprite/Mesh Render Layout and Sprite/Mesh Render Buffer or Sprite Surfaces. Unique render data stores Render Resource information (Sprite material or Mesh from IOFX asset) and a range (defined by startIndex and objectCount) which points to the corresponding shared render buffer.

Shared Render Buffers & Surfaces

Shared render buffers for both Sprites & Meshes are implemented using UserRenderBuffer interface, and shared render surfaces for Sprites are implemented using UserRenderSurface interface.

To access render data on CPU for both render buffer & surface user have to use map/unmap methods.

By default APEX creates simple render buffer/surface internally based on given render layout, it just stores render data in CPU memory, and user need to map render buffer/surface, then copy its content to user graphics resource, and finally unmap it. This way is simple but not efficient, so APEX has another way for user to provide its own implementation for render buffer/surface, by overriding createRenderBuffer() & createRenderSurface() methods in IofxRenderCallback.

For CPU access user need to implement map/unmap methods, and can directly map/unmap graphics buffer, eliminating data copy.

When IOS simulation is done on GPU there is still overhead to copy data from GPU (compute) to CPU and back from CPU to GPU (graphics), and to eliminate this overhead IOFX supports compute-graphics interop, when IOFX writes render data directly into user graphics buffer on GPU. In order for interop to work, user have to implement getCUDAgraphicsResource() method in UserRenderBuffer/UserRenderSurface.

Render Volumes

RenderVolumes are the primary renderables of the APEX Particles pipeline. A volume “owns” a portion of world space, though ownership volumes are explictly allowed to overlap. Volumes are created via an IOFx module method:

RenderVolume *createRenderVolume( const Scene& apexScene, const PxBounds3& b, PxU32 priority, bool allIofx );

The bounds argument defines the volume’s ownership bounds. The priority is used to break ties when particles are within multiple volumes. If a particle is within multiple volumes of the same priority, it will prefer its previous volume when possible. The allIofx flag determines whether a volume will take ownership of all particles within its bounds, or only those particles emitted to specific IOFX assets.

The game may create or release render volumes at any time, their insertions and deletions are queued to make them thread-safe. As volumes take ownership of particles, IOFX actors are instantiated on demand to manage the render resources required to draw them. This deferred IOFX actor creation may be disabled via an IOFx module method: disableDeferredRenderableAllocation().

Calling getBounds() on the render volume will return the bounds of all the particles in that render volume that frame. It is usually much smaller than the volume’s ownership bounds and should be used for culling purposes. Culling a render volume implicitly culls all of the IOFX actors it holds.

If a particle is not owned by any volume at the end of a simulation step, it is considered “homeless” and is not rendered. It will be deleted on the next simulation step.

PxBounds3 b; b.setInfinite();
vol = IofxModule->createRenderVolume( scene, infBounds, 0, true );
emitterActor->setPreferredRenderVolume( vol );

if (visibilityCheck(mVolume->getBounds())
{
    uint32_t numIofxActors;
    IofxActor* const* iofxActors = mVolume->lockIofxActorList(numIofxActors);
    for (uint32_t i = 0 ; i < numIofxActors ; i++)
    {
        IofxRenderable* renderable = iofxActors[i]->acquireRenderableReference();
        if (renderable)
        {
            if (visibilityCheck(renderable->getBounds())
            {
                if (const IofxSpriteRenderData* spriteRenderData = renderable->getSpriteRenderData())
                {
                    renderSprites(spriteRenderData);
                }
                else
                if (const IofxMeshRenderData* meshRenderData = renderable->getMeshRenderData())
                {
                    renderMeshes(meshRenderData);
                }
            }
            renderable->release();
        }
    }
    mVolume->unlockIofxActorList();
}

Errors and Warnings

APEX IOFx outputs the following error and warning messages using the standard APEX error stream. All are caused by authoring problems.