Creation and Destruction

This page explains creation and destruction. For creation, this page describes loading and operating on ResGraphicsFiles, generating instances, and registering to a scene tree. For destruction, this page describes precautions when destroying generated instances.

Loading and Setting Up a ResGraphicsFile

The first step is to load the particle binary (a bcptl file) and prepare the ResGraphicsFile. The demo uses the demo::Utility::LoadResources function. Call the gfx::ResGraphicsFile::Setup function once the file is done loading. Generation up to this point is the same as for the SkeletalModel and Model objects. See Model Display for more details.

ResGraphicsFile Operations

You can configure the following gfx::ResGraphicsFile settings for particles.

Loading ResGraphicsFile Textures into VRAM

　Load textures into VRAM for faster processing. You must configure this setting before calling the gfx::ResGraphicsFile::Setup function. See Using VRAM for details.

Using Material Classes Dedicated to Particles

　Use a material class dedicated to particles for faster processing. See Using ParticleMaterialActivator for details.

Configuring Shader Resources

　If the binary was output with separate shader resources, you must load these and configure them.

// Sample code for attaching shader resources loaded from external files.

nw::demo::ResourceSet*    shaderResource;
nw::gfx::ResGraphicsFile* graphicsFile;

// Load shader resource from file.
{
    shaderResource = deviceAllocator->AllocAndConstruct<nw::demo::ResourceSet>(1);
    shaderResource.buffer = 
                nw::demo::Utility::LoadFile(deviceAllocator, "nwgfx_ParticleDefaultShader.bcsdr");
    shaderResource.resource = 
                nw::gfx::ResGraphicsFile(&(shaderResource->buffer.front()));
}

// Set up the resource, and if there are no shader resources, specify the separately loaded shader resources and set up again.
// 
nw::gfx::Result result = graphicsFile.Setup(deviceAllocator);

if(result.IsFailure())
{
    if (result.GetDescription() & nw::gfx::RESOURCE_RESULT_NOT_FOUND_SHADER)
    {
        result = graphicsFile.Setup(deviceAllocator, shaderResource);
    }
}

Generating Instances

Generate instances of the ParticleModel and ParticleEmitter classes from the loaded ResGraphicsFile. Call the nw::gfx::SceneBuilder function to generate instances. Then call the gfx::SceneHelper::ResolveReference function to resolve references for the generated instances. Generation up to this point is the same as for the SkeletalModel and Model objects. See Model Display for more details.

For particles, you must also call the gfx::ParticleUtil::SetupParticleObject function to resolve internal references and initialize random numbers.

Resolving Internal References for Particles

References are resolved within an array given as an argument. You must take care within the array to avoid ParticleSet/ParticleEmitter name collisions. The array is passed as an argument in order to explicitly limit the scope of references. This is useful when creating multiple instances from a single resource.

Initializing Random Numbers

Initialize the ParticleEmitter and ParticleSet random number seeds using the random number from nw::gfx::ParticleContext.

Particle Class Internal References

There are basically three different particle classes: ParticleModel, ParticleSet, and ParticleEmitter. The reference relationships for each are as follows. Access is only possible in the direction of the arrows.

　　　　　　　　　 Has a:
　　[ParticleModel] → [ParticleSet] ← [ParticleEmitter]
                                    References

The gfx::ParticleUtil::SetupParticleObject function internally resolves ParticleEmitter references to the ParticleSet instance to be emitted.

Registering to the Scene Tree

The particle animation begins playing once you register all initialized instances to the scene tree. You must call SceneInitializer or SceneTraverser after registering.

Destroying Instances

You must take care when destroying any ParticleModel or ParticleEmitter instances, and when releasing any render buffers. After issuing any rendering commands, do not destroy any instances until the drawing is actually complete. Destroying an instance after issuing a rendering command is extremely dangerous as the GPU might try to access the render buffer belonging to the destroyed instance. The same goes for textures. When command buffers are doubled, the GPU attempts to access the render buffer the frame after a rendering command is issued, so you must skip one frame before destroying any instances.

Precautions when Generating or Destroying Instances

Object generation and destruction are very expensive processes. When playing the animation for the same particle multiple times, Nintendo recommends reusing the same instance rather than generating and destroying particle objects for every animation playback. See About Reusing Instances for details on reusing instances.

CONFIDENTIAL