Building and Running the Samples on Windows

This guide explains the code from a series of samples:

• The Hello World Sample shows a minimal physx setup.
• The North Pole Sample demonstrates basic functionality covered in Startup and Shutdown, Scenes, Materials, and Actors, Shapes and Geometries, and Rigid Body Dynamics.
• The Bridges Sample demonstrates joints, described in the chapter Joints, as well as the character controller explained in Character Controllers.
• The Vehicle Sample demonstrates the use of vehicles described in the chapter Vehicles.
• The Particles Sample demonstrates the use of particle effects, which is the topic of Particles.
• The Character Cloth Sample demonstrates clothing functionality, described in the chapter Cloth.
• The Custom Gravity Sample demonstrates using the character controller in a context where the vertical direction is not fixed.
• Finally, the Submarine Sample shows off a number of advanced features, which receive a treatment in the chapters Scene Queries, Callbacks and Customization, Advanced Rigid Body Topics, and Task Management.

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.

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.

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.

The API

The PhysX SDK exposes an application programming interface (API) composed primarily of abstract interface classes. The header files that belong to the public API are located in a top level directory named "Include". Classes, enumerations and functions defined by the public API have the prefix Px. We are committed to keeping this API stable and backwards-compatible from one minor release to the next, to protect the investment you make in your integration code.

The PhysX libraries also expose some classes and functions that are not part of the public API, such as container and platform abstractions that we find practical to reuse in our samples. These are largely undocumented, and can be recognized because they do not have the Px prefix of the public API. While they are technically available to users, most users either will not need them or will have their own versions, and we are not committed to backwards-compatibility of this code between PhysX versions.

Multithreading

PhysX provides efficient multithreaded implementations of its simulation and raycasting functionality. See Task Management for details of integrating PhysX threading into an application.

For efficiency reasons, PhysX does not internally lock access to its data structures by the application, so be careful when calling the API from multiple application threads. The rules are as follows:

• API interface methods marked 'const' are read calls, other API interface methods are write calls.
• API read calls may be made simultaneously from multiple threads.
• Objects in different scenes may be safely accessed by different threads.
• Different objects outside a scene may be safely accessed from different threads. Be aware that accessing an object may indirectly cause access to another object via a persistent reference (such as joints and actors referencing one another, an actor referencing a shape, or a shape referencing a mesh.)

Access patterns which do not conform to the above rules may result in data corruption, deadlocks, or crashes. Note in particular that it is not legal to perform a write operation on an object in a scene concurrently with a read operation to an object in the same scene. The checked build contains code which tracks access by application threads to objects within a scene, to try and detect problems at the point when the illegal API call is made.

Read and write calls may be made to objects in a scene that is being simulated. See Data Access and Buffering for details.

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.