The Basics

Welcome to the NVIDIA® PhysX® SDK version 3! With this second major rewrite of the SDK, we are excited to bring you a great number of enhancements, including numerous API improvements. Because so much has changed in the API, we recommend even experienced PhysX users to read through this guide to familiarize themselves with the new programming interface.

Users migrating from PhysX 2 will find the Migrating From PhysX SDK 2.x to 3.x chapter of particular interest.

Release Layout

Depending on your license, we provide you with the Core Installer or with the Source installer of the PhysX SDK:

Core Installer

Bin/                       Executables and dlls in platform specific folders
Documentation/             PhysXGuide & PhysXAPI documentation
externals/                 External libraries
Include/                   API Include Headers
Lib/                       Libraries in platform specific folders
media/                     Media files
Samples/                   PhysX Samples, solutions are in the compiler folder
Snippets/                  PhysX Code Snippets, solutions are in the compiler folder
Source/                    Public Source Code
  GeomUtils/               Geometry Math
  PhysXCharacterKinematic/ Character Controller
  PhysXExtensions/         Extensions, Helper Classes
  PhysXMetaData/           Serialization
  PhysXProfileSDK/         Profiling SDK
  PhysXVehicle/            Vehicle Controller
Tools/                     MetaData Generator
readme_???.html            Platform specific readme file
release_notes.html         PhysX Release Notes
version-PhysX.txt          PhysX version and build number of this installer

Source Installer

Bin/                       Executables and dlls in platform specific folders
Documentation/             PhysXGuide & PhysXAPI Documentation
externals/                 External libraries
Include/                   API Include Headers
Lib/                       Libraries in platform specific folders
media/                     Media files
Samples/                   PhysX Samples, solutions are in the compiler folder
Snippets/                  PhysX Code Snippets, solutions are in the compiler folder
Source/                    Full Source Code (see core installer for details about the public sections)
Tools/                     MetaData Generator
readme_???.html            Platform specific readme file
release_notes.html         PhysX Release Notes
version-PhysX.txt          PhysX version and build number of this installer

Building and Running the Samples on Windows

This guide explains the code from a series of samples:

On Windows, PhysX requires either Visual Studio 2008 with Service Pack 1 or higher, or Visual Studio 2010.

To see the samples, open the Visual Studio solution called Samples.sln. This includes the samples listed above within the project Samples, plus some additional projects which implement common operations.

Snippets

PhysX Code Snippets show the basic usage of PhysX features. Please see each snippet for usage details.

Snippets rendering is supported only on these platforms: Win32, Win64, OSX, Linux and Ps3.

Build Settings

While not particularly important for understanding the Sample code, to build your own PhysX app, you will need to add some include paths and libraries to your project makefile or IDE. The include files and libraries are located in the root folders "Include" and "Lib" respectively. A number of these include directories and libraries are of course only needed if the corresponding component, such as the Vehicle library, is used. You will also need to add the apropriate platform specific extension for libs (e.g. ".lib" or ".a") and the apropriate relative path prefixes (e.g. "../../") for includes.

Note

The static libraries we provide with the Windows binary distribution are linked against the Multi-Threaded static C Run-Time (CRT) libraries. This means that your application must also use the same CRT flavor. If you need to use a different CRT version, you must upgrade to our source license. The source distribution can simply be recompiled using different CRT settings.

Library Redistribution

On the Windows platform, you need to redistribute some of our DLLs to end users as part of your application:

  • PhysX3Common_*.dll - will always be needed.
  • PhysX3_*.dll - will always be needed.
  • PhysX3Cooking_*.dll - you only need to bundle if your application cooks geometry data on the fly.
  • PhysX3GPU_*.dll - is only needed if your application runs some simulation on the GPU.
  • PhysX3CharacterKinematic_*.dll- is only needed if your application uses the character controller.

Where * is a platform specific suffix, e.g. x86 or x64. You will need one or the other depending on whether your application is built in 64 bit mode.

Build Configurations

The SDK has three build configurations available to all licensees, designed for different stages of development and deployment.

  • the checked build contains code to detect invalid parameters, API race conditions, and other incorrect uses of the API which might otherwise cause mysterious crashes or failures in simulation.
  • the profile build omits the checks, but still has PVD and memory instrumentation.
  • the release build is built for minimal footprint and maximum speed. It omits most checks and instrumentation.

Simulation works the same way in all of them, and all are compiled with high optimization levels. In addition, you can build components of PhysX which ship with source in a debug configuration, which is compiled without optimizations. The debug build can be useful for error analysis, but contains asserts used for SDK development which some customers may find too intrusive for daily use.

Note

We strongly recommend that you use the checked build as the primary configuration for day-to-day development and QA.

Note

PhysX libraries of different build configurations (e.g. the DEBUG version of PhysXVehicle and the CHECKED version of PhysXVisualDebuggerSDK) should never be mixed in an application because this will also result a CRT conflict.

PhysX Visual Debugger

The PhysX Visual Debugger (PVD) provides a graphical view of the PhysX scene together with various tools to inspect and visualize variables of every PhysX object. Additionally it can also record and visualize memory and timing data. See PhysX Visual Debugger (PVD) for details.