.. _pvd-label:

=====================
PhysX Visual Debugger
=====================

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

The PhysX Visual Debugger (PVD) provides APEX and PhysX with a mechanism for displaying profiling events, memory tracking,
and external debug visualization.  APEX does not route any debug visualization to PVD, just profiling and memory
data.  Many of the APEX framework and module classes contain profiling zones which assist in isolating performance
issues.

.. image:: images/PVD_Profile_Window.PNG
   :width: 60%

For convenience, APEX automatically creates a PVD camera from the view matrix the application gives to an Scene. Look for "ApexCamera 0" in the PVD cameras.

APEX also supports limited PVD object debugging to show APEX module, asset, and actor properties. Currently only clothing is supported. When object debugging is enabled, you will also be able to visualize the clothing in PVD by enabling Constraints visualization in the PVD Preferences.

When connecting to PVD with any method (object debugging, profiling, or memory tracking) the APEX error stream will automatically be routed to PVD's error stream display.

Get PVD
-------

Go to `http://developer.nvidia.com/physx-visual-debugger <http://developer.nvidia.com/physx-visual-debugger>`_ to get PVD.


Supported Configurations
------------------------

See the :ref:`deployment-build-configs-label` section for information on which configurations
support PVD connections.

Connecting to PVD
-----------------

To connect APEX and PhysX to PVD, the application must get APEX's PVD Binding using the ApexSDK::getPvdBinding() method.
The PvdBinding class provides connect and disconnect methods which allow the user to specify the IP address and port
of the computer running PVD and the connection flags.

`PVD::PvdBinding* ApexSDK::getPvdBinding() <../_static/build_framework/classphysx_1_1apex_1_1_nx_apex_s_d_k.html>`_ 

`class PvdBinding <../_static/build_framework/class_p_v_d_1_1_pvd_binding.html>`_ 

.. note:: The debug visualization connection flag (physx::debugger::PvdConnectionType::eDEBUG) will greatly reduce performance and should not be paired with the profile flag (physx::debugger::PvdConnectionType::ePROFILE) because the profile results will be inflated.

Example
-------

This function will toggle the PVD connection for profiling only::

    #include <ApexSDK.h>
    #include <PVDBinding.h>

    using namespace physx::apex;
    using namespace PVD;

    void togglePvdConnection()
    {
        PvdBinding* theBinding = GetApexSDK()->getPvdBinding();
        if (theBinding != NULL)
        {
            if (theBinding->isConnected())
            {
                theBinding->disconnect();
            }
            else
            {
                theBinding->connect("localhost", 
                                    DEFAULT_PVD_BINDING_PORT, 
                                    DEFAULT_PVD_BINDING_TIMEOUT_MS, 
                                    physx::debugger::PvdConnectionType::ePROFILE);
            }
        }
    }

Android Notes
-------------

Remotely connecting to PVD from Android is supported via a Wi-Fi connection. But it is preferrable to save PVD information to a file because it works faster and produces more reliable information.

To get PVD information on Android from APEX samples you should uncomment this line from framework\\src\\PVDBinding.cpp:
    getConnectionManager().connect( *this, "/sdcard/media/out.pxd2", inConnectionType );
	
	
The PVD dump will be recorded in the corresponding file - out.pxd2. Note that access to APEX source code is required to make this change.

