1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
2<html xml:lang="en-US" lang="en-US">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../../../css/document.css" type="text/css" />
7    <title>Creation and Destruction</title>
8  </head>
9  <body>
10    <h1>Creation and Destruction</h1>
11  <div class="section">
12
13    <p>This page explains creation and destruction. For creation, this page describes loading and operating on <CODE>ResGraphicsFile</CODE>s, generating instances, and registering to a scene tree. For destruction, this page describes precautions when destroying generated instances.</p>
14
15    <h2><a name="resgraphicsload" id="resgraphicsload"></a>Loading and Setting Up a <CODE>ResGraphicsFile</CODE></h2>
16    <p>The first step is to load the particle binary (a <CODE>bcptl</CODE> file) and prepare the <CODE>ResGraphicsFile</CODE>. The demo uses the <CODE>demo::Utility::LoadResources</CODE> function. Call the <CODE>gfx::ResGraphicsFile::Setup</CODE> function once the file is done loading. Generation up to this point is the same as for the <CODE>SkeletalModel</CODE> and <CODE>Model</CODE> objects. See <a href="../BasicFeature.html#play">Model Display</a> for more details.</p>
17
18
19    <h2><a name="resgraphics" id="resgraphics"></a><CODE>ResGraphicsFile</CODE> Operations</h2>
20    <p>You can configure the following <CODE>gfx::ResGraphicsFile</CODE> settings for particles.</p>
21
22    <h3>Loading <CODE>ResGraphicsFile</CODE> Textures into VRAM</h3>
23    <p>　Load textures into VRAM for faster processing. You must configure this setting before calling the <CODE>gfx::ResGraphicsFile::Setup</CODE> function. See <a href="../Particle/Draw.html#usevram">Using VRAM</A> for details.<p>
24
25    <h3>Using Material Classes Dedicated to Particles</h3>
26    <p>　Use a material class dedicated to particles for faster processing. See <a href="../Particle/Draw.html#useparticlematerial">Using <CODE>ParticleMaterialActivator</CODE></a> for details.</p>
27
28    <h3>Configuring Shader Resources</h3>
29    <p>　If the binary was output with separate shader resources, you must load these and configure them.</p>
30<pre>
31// Sample code for attaching shader resources loaded from external files.
32
33nw::demo::ResourceSet*    shaderResource;
34nw::gfx::ResGraphicsFile* graphicsFile;
35
36// Load shader resource from file.
37{
38    shaderResource = deviceAllocator-&gt;AllocAndConstruct&lt;nw::demo::ResourceSet&gt;(1);
39    shaderResource.buffer =
40                nw::demo::Utility::LoadFile(deviceAllocator, &quot;nwgfx_ParticleDefaultShader.bcsdr&quot;);
41    shaderResource.resource =
42                nw::gfx::ResGraphicsFile(&(shaderResource-&gt;buffer.front()));
43}
44
45// Set up the resource, and if there are no shader resources, specify the separately loaded shader resources and set up again.
46//
47nw::gfx::Result result = graphicsFile.Setup(deviceAllocator);
48
49if(result.IsFailure())
50{
51    if (result.GetDescription() & nw::gfx::RESOURCE_RESULT_NOT_FOUND_SHADER)
52    {
53        result = graphicsFile.Setup(deviceAllocator, shaderResource);
54    }
55}
56</pre>
57
58    <h2><a name="createinst" id="createinst"></a>Generating Instances</h2>
59    <p>Generate instances of the <CODE>ParticleModel</CODE> and <CODE>ParticleEmitter</CODE> classes from the loaded <CODE>ResGraphicsFile</CODE>. Call the <CODE>nw::gfx::SceneBuilder</CODE> function to generate instances. Then call the <CODE>gfx::SceneHelper::ResolveReference</CODE> function to resolve references for the generated instances. Generation up to this point is the same as for the <CODE>SkeletalModel</CODE> and <CODE>Model</CODE> objects. See <a href="../BasicFeature.html#play">Model Display</a> for more details.<br /><br /> For particles, you must also call the <CODE>gfx::ParticleUtil::SetupParticleObject</CODE> function to resolve internal references and initialize random numbers.</p>
60
61    <h3>Resolving Internal References for Particles</h3>
62    <p>References are resolved within an array given as an argument. You must take care within the array to avoid <CODE>ParticleSet</CODE>/<CODE>ParticleEmitter</CODE> 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.</p>
63
64    <h3>Initializing Random Numbers</h3>
65    <p>Initialize the <CODE>ParticleEmitter</CODE> and <CODE>ParticleSet</CODE> random number seeds using the random number from <CODE>nw::gfx::ParticleContext</CODE>.</p>
66
67    <h3>Particle Class Internal References</h3>
68    <p>There are basically three different particle classes: <CODE>ParticleModel</CODE>, <CODE>ParticleSet</CODE>, and <CODE>ParticleEmitter</CODE>. The reference relationships for each are as follows. Access is only possible in the direction of the arrows.</p>
69<pre>
70　　　　　　　　　 Has a:
71　　[<CODE>ParticleModel</CODE>] → [<CODE>ParticleSet</CODE>] ← [<CODE>ParticleEmitter</CODE>]
72                                    References
73</pre>
74
75    <p>The <CODE>gfx::ParticleUtil::SetupParticleObject</CODE> function internally resolves <CODE>ParticleEmitter</CODE> references to the <CODE>ParticleSet</CODE> instance to be emitted.<p />
76
77
78    <h2>Registering to the Scene Tree</h2>
79    <p>The particle animation begins playing once you register all initialized instances to the scene tree. You must call <CODE>SceneInitializer</CODE> or <CODE>SceneTraverser</CODE> after registering.</p>
80
81
82    <h2>Destroying Instances</h2>
83    <p>You must take care when destroying any <CODE>ParticleModel</CODE> or <CODE>ParticleEmitter</CODE> 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.</p>
84
85
86    <h2>Precautions when Generating or Destroying Instances</h2>
87    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 <a href="../Particle/Attention.html#reuse">About Reusing Instances</a> for details on reusing instances.
88
89  </div>
90  <hr><p>CONFIDENTIAL</p></body>
91</html>
92