.. _debug-visualization-label:

===================
Debug Visualization
===================

Introduction
------------

Debug visualization features can be controlled using parameters which are stored
using separate NvParameterized classes - one for general debug rendering
parameters, and one for each loaded module which stores parameters specific
to that module. Specific details on parameters can be found in their respective
module's programmers guides.

To get the NvParameterized object for debug rendering parameters,
the following must be done::

    //Get APEX framework debug rendering parameters
    NvParameterized::Interface &dbgRenderParams = *m_apexScene->getDebugRenderParams();
    //Get clothing debug rendering parameters
    NvParameterized::Interface &dbgRenderParamsClothing = *m_apexScene->getModuleDebugRenderParams("Clothing");
    //Get emitter debug rendering parameters
    NvParameterized::Interface &dbgRenderParamsEmitter = *m_apexScene->getModuleDebugRenderParams("Emitter");

Framework Parameters
--------------------

The APEX Framework has a set of parameters to control debug visualization for items at the framework level:

* `APEX Framework <../_static/build_params/structDebugRenderParams.html>`_
	
Module List
-----------

Module names must be selected from this list (with links to the parameter descriptions):

.. only:: SDKver3X

    * `BasicFS <../_static/build_params/structBasicFSDebugRenderParams.html>`_
    * `BasicIos <../_static/build_params/structBasicIosDebugRenderParams.html>`_
    * `Clothing <../_static/build_params/structClothingDebugRenderParams.html>`_
    * `Destructible <../_static/build_params/structDestructibleDebugRenderParams.html>`_
    * `Emitter <../_static/build_params/structEmitterDebugRenderParams.html>`_
    * `ForceField <../_static/build_params/structForceFieldDebugRenderParams.html>`_
    * `Iofx <../_static/build_params/structIofxDebugRenderParams.html>`_
    * `TurbulenceFS <../_static/build_params/structTurbulenceFSDebugRenderParams.html>`_

Examples
--------

After getting the NvParameterized object, parameters can be modified. Sample
code which modifies debug rendering parameters are as follows::

    // It is important to enable the global debug visualization
    NvParameterized::setParamBool(dbgRenderParams, "Enable", true);
    // The scale of the debug visualization may be altered globally
    NvParameterized::setParamF32(dbgRenderParams, "Scale", 1.0f);
    // Draw the simulation mesh for clothing actors, scaled to 90%
    NvParameterized::setParamF32(dbgRenderParamsClothing, "PhysicsMeshWire", 0.9f);
    // The APEX emitters feature some hierarchy, so the dot notation gets you to the individual parameters
    NvParameterized::setParamBool(dbgRenderParamsEmitter, "apexEmitterParameters.VISUALIZE_APEX_EMITTER_ACTOR", true);
    NvParameterized::setParamBool(dbgRenderParamsEmitter, "groundEmitterParameters.VISUALIZE_GROUND_EMITTER_RAYCAST", true);
	
.. note::
    Debug rendering parameters for emitters are further subclassed into apex,
    ground and impact emitter parameters. Refer to the emitter programmers
    guide for more details.

The APEX debug rendering is output through the APEX scene's render resources interface::

    // render debug-render scene
    m_apexScene->lockRenderResources();
    m_apexScene->updateRenderResources();
    m_apexScene->dispatchRenderResources(*m_apexRenderer);
    m_apexScene->unlockRenderResources();
	
The application may also tunnel the PhysX debug rendering (DebugRenderable or PxRenderBuffer) through 
the APEX rendering interface::

    nvidia::apex::RenderDebug* m_apexRenderDebug = m_apexSDK->createApexRenderDebug();
    #if PX_PHYSICS_VERSION_MAJOR == 2
        const DebugRenderable* debugRenderable = m_apexScene->getPhysXScene()->getDebugRenderable();
        if (debugRenderable)
        {
            m_apexRenderDebug->addDebugRenderable(*debugRenderable);
        }
    #elif PX_PHYSICS_VERSION_MAJOR == 3
        const physx::PxRenderBuffer& renderBuffer = m_apexScene->getPhysXScene()->getRenderBuffer();
        if (m_apexRenderDebug != NULL)
        {
            m_apexRenderDebug->addDebugRenderable(renderBuffer);
        }
    #endif


Debug Rendering Colors
----------------------
Debug rendering uses the following table of colors:

+-----------------+----------------+------------------------------------------+
| Color Parameter | Default (ARGB) | Description                              |
+=================+================+==========================================+
| Default         | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| PoseArrows      | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| MeshStatic      | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| MeshDynamic     | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Shape           | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Text0           | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Text1           | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| ForceArrowsLow  | 0xFFFFFF00     | Forcefield arrows in wind/explosion      |
+-----------------+----------------+------------------------------------------+
| ForceArrowsNorm | 0xFF00FF00     | Forcefield arrows in wind/explosion      |
+-----------------+----------------+------------------------------------------+
| ForceArrowsHigh | 0xFFFF0000     | Forcefield arrows in wind/explosion      |
+-----------------+----------------+------------------------------------------+
| Color0          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Color1          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Color2          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Color3          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Color4          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Color5          | 0x00000000     | Currently unused                         |
+-----------------+----------------+------------------------------------------+
| Red             | 0xFFFF0000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Green           | 0xFF00FF00     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Blue            | 0xFF0000FF     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| DarkRed         | 0xFF800000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| DarkGreen       | 0xFF008000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| DarkBlue        | 0xFF000080     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| LightRed        | 0xFFFF8080     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| LightGreen      | 0xFF80FF00     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| LightBlue       | 0xFF00FFFF     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Purple          | 0xFFFF00FF     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| DarkPurple      | 0xFF800080     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Yellow          | 0xFFFFFF00     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Orange          | 0xFFFF8000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Gold            | 0xFF808000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Emerald         | 0xFF008080     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| White           | 0xFFFFFFFF     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Black           | 0x00000000     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| Gray            | 0xFF808080     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| LightGray       | 0xFFC0C0C0     | Standard colors                          |
+-----------------+----------------+------------------------------------------+
| DarkGray        | 0xFF404040     | Standard colors                          |
+-----------------+----------------+------------------------------------------+

Debug rendering colors are stored using NvParameterized, and can be customized
by first getting the NvParameterized object, then modifying the parameters as
follows::

    //Initialize debug colors parameters
    NvParameterized::Interface &dbgColorParams = *GetApexSDK()->getDebugColorParams();
    NvParameterized::setParamU32(dbgColorParams, "Red", 0xFFFFFF00);
    NvParameterized::setParamU32(dbgColorParams, "ForceArrowsNorm", 0xFFFF0000);

The above code will replace any existing red draw code with yellow, and replacing
green with red for normal forcefield arrows in wind and explosion modules.

