User's Guide

Built January 23, 2019

Contents:

• PhysX License
• Welcome to PhysX
  • About this User Guide
  • A brief overview of PhysX
  • World and Objects
  • Rendering and Visualization
• Snippets
  • What are PhysX Snippets?
  • HelloWorld: PhysX Basics
  • Using PhysX Visual Debugger with SnippetHelloWorld
• Building with PhysX
  • Generating projects with CMake
  • Build Configurations
  • Header Files
  • Redistribution
  • Customize CMake presets
• The PhysX API
  • Introduction
  • Memory Management
  • Error Reporting
  • Math Classes
  • Connecting PhysX Objects with User Application Objects
  • Type Casting
  • Reference Counting
  • Using Different Units
  • Assertions
  • Determinism
• Startup and Shutdown
  • Introduction
  • Foundation and Physics
  • Cooking
  • Extensions
  • Optional SDK Components
  • Delay-Loading DLLs
    • PhysXCommon DLL and PhysXFoundation DLL load
    • PxDelayLoadHook
    • PxGpuLoadHook
    • PhysXCommon Secure Load
  • Shutting Down
• Threading
  • Introduction
  • Data Access from Multiple Threads
    • Scene Locking
    • Locking Semantics
    • Locking Best Practices
  • Asynchronous Simulation
    • Double Buffering
    • Events involving removed objects
    • Memory Considerations
  • Multithreaded Simulation
    • TaskManager
    • CpuDispatcher
    • CpuDispatcher Implementation Guidelines
    • BaseTask
    • Task
    • LightCpuTask
• Geometry
  • Introduction
  • Geometry Types
    • Spheres
    • Capsules
    • Boxes
    • Planes
    • Convex Meshes
    • Convex Mesh cooking
    • Triangle Meshes
    • Height Fields
  • Deformable meshes
  • Mesh Scaling
  • PxGeometryHolder
  • Vertex and Face Data
    • Convex Meshes
    • Triangle Meshes
    • Height Fields
    • Heightfield Modification
• Rigid Body Overview
  • Introduction
  • Rigid Body Object Model
  • The Simulation Loop
• Rigid Body Collision
  • Introduction
  • Shapes
  • Simulation Shapes and Scene Query Shapes
  • Kinematic Triangle Meshes (Planes, Heighfields)
  • Broad-phase Algorithms
  • Regions of Interest
  • Broad-phase Callback
  • Collision Filtering
  • Aggregates
  • Creating an Aggregate
  • Populating an Aggregate
  • Releasing an Aggregate
  • Amortizing Insertion
  • Trigger Shapes
  • Interactions
• Rigid Body Dynamics
  • Velocity
  • Mass Properties
  • Applying Forces and Torques
  • Gravity
  • Friction and Restitution
  • Sleeping
    • Sleep state change events
  • Kinematic Actors
    • Kinematic Surface Velocities
  • Active Actors
  • Dominance
  • Solver Iterations
  • Immediate Mode
  • Enhanced Determinism
  • Axis locking
  • Temporal Gauss-Seidel
• Simulation
  • Callback Sequence
  • Simulation memory
    • Scene Limits
    • 16K Data Blocks
    • Scratch Buffer
    • In-place Serialization
    • PVD Integration
  • Completion Tasks
  • Synchronizing with Other Threads
  • Substepping
  • Split sim
  • Split fetchResults
• Advanced Collision Detection
  • Tuning Shape Collision Behavior
  • Contact Modification
  • Contact reporting
    • Contact Reports and CCD
  • Extracting Contact information
    • Extra Contact Data
  • Continuous Collision Detection
    • Contact Notification and Modification
    • Triggers
    • Tuning CCD
    • Performance Implications
    • Limitations
  • Raycast CCD
  • Speculative CCD
  • Persistent Contact Manifold (PCM)
• Joints
  • Joint Basics
    • Visualization
    • Force Reporting
    • Breakage
    • Projection
    • Limits
    • Actuation
    • Mass Scaling
  • Fixed Joint
  • Spherical Joint
  • Revolute Joint
  • Prismatic Joint
  • Distance Joint
  • D6 Joint
    • Locking and Unlocking Axes
    • Limits
    • Drives
    • Configuring Joints for Best Behavior
  • Custom Constraints
    • Defining Constraint Behavior
    • The Constraint Shader Table
    • Data Management
• Articulations
• Maximal Coordinate and Reduced Articulations
• Maximal Coordinate Articulations
  • Creating an Articulation
  • Articulation Joints
  • Driving an Articulation
  • Articulation Projection
  • Articulations and Sleeping
• Reduced Coordinate Articulations
  • Creating a Reduced Coordinate Articulation
  • Articulation Joints
  • Joint positions and velocities
  • PxArticulationCache
  • Inverse Dynamics
• Scene Origin
  • Shifting The Scene Origin
• GPU Rigid Bodies
  • Introduction
  • Using GPU Rigid Bodies
  • What is GPU accelerated?
  • Tuning
  • Performance Considerations
• Geometry Queries
  • Introduction
  • Raycasts
    • Raycasts against Spheres, Capsules, Boxes and Convex Meshes
    • Raycasts against Planes
    • Raycasts against Triangle Meshes
    • Raycasts against Heightfields
  • Overlaps
  • Penetration Depth
  • Sweeps
    • Initial Overlaps
    • Precise Sweeps
    • Sweeps against Height Fields
    • Pitfalls
  • Additional PxGeometryQuery functions
  • PxMeshQuery
    • Mesh Overlaps
    • Sweeps against Triangles
• Scene Queries
  • Introduction
  • Basic queries
    • Raycasts
    • Sweeps
    • Overlaps
  • Touching and blocking hits
  • Query modes
    • Closest hit
    • Any hit
    • Multiple hits
    • Multiple hits with blocking hit
  • Filtering
    • PxQueryFlag::eSTATIC, PxQueryFlag::eDYNAMIC
    • PxQueryFlag::ePREFILTER, PxQueryFlag::ePOSTFILTER
    • PxQueryFlag::eANY_HIT
    • PxQueryFlag::eNO_BLOCK
    • PxFilterData fixed function filtering
  • User defined hit callbacks for unbounded results
  • Batched queries
  • Single Object Caching
  • PxPruningStructureType
    • Generalities
    • PxPruningStructureType::eNONE
    • PxPruningStructureType::eSTATIC_AABB_TREE
    • PxPruningStructureType::eDYNAMIC_AABB_TREE
  • PxSceneQueryUpdateMode
  • PxPruningStructure
    • Merge process
  • PxBVHStructure
    • How to create PxBVHStructure
• Vehicles
  • Introduction
  • Algorithm
  • First Code
    • Vehicle SDK Initialization
    • Introduction To Vehicle Creation
    • Introduction To Vehicle Update
  • Snippets
    • SnippetVehicle4W
    • SnippetVehicleTank
    • SnippetVehicleNoDrive
    • SnippetVehicleScale
    • SnippetVehicleMultiThreading
  • Advanced Concepts
    • Vehicle Creation
    • Filtering
    • Tire Friction on Drivable Surfaces
    • Vehicle Controls
    • Vehicle Update
  • More Advanced Concepts
    • Vehicle Telemetry
    • Vehicle Update Multi-Threaded
    • Tire Shaders
    • Vehicle Types
    • SI Units
    • Level of Detail
    • Wheel Contact Beyond Raycasts
  • Tuning Guide
    • PxVehicleWheelData
    • PxVehicleWheelsSimData
    • PxVehicleSuspensionData
    • PxVehicleAntiRollBar
    • PxVehicleTireData
    • PxVehicleEngineData
    • PxVehicleGearsData
    • PxVehicleAutoBoxData
    • PxVehicleClutchData
    • PxVehicleAckermannGeometryData
    • PxVehicleTireLoadFilterData
    • PxVehicleDifferential4WData
    • PxRigidDynamic
  • Troubleshooting
    • Jittery Vehicles
    • The Engine Rotation Refuses To Spin Quickly
    • The Engine Spins But the Wheels Refuse To Spin
    • The Wheels Are Spinning But The Vehicle Does Not Move Forwards
    • The Vehicle Does Not Steer/Turn
    • The Acceleration Feels Sluggish
    • The Vehicle Does Not Slow Down When Not Accelerating
    • The Vehicle Turns Too Quickly/Too Slowly
    • The Wheels Spin Too Much Under Acceleration
    • The Wheels Spin Too Much When Cornering
    • The Vehicle Never Goes Beyond First Gear
    • The Vehicle Under-steers Then Over-steers
    • The Vehicle Slows Down Unnaturally
    • The Vehicle Climbs Too Steep Slopes
  • References
    • Anti-roll Bar
    • Tire Modeling
    • Engine Torque Curves
    • Differentials
    • Clutch
    • Ackermann Steer Correction
    • Tanks
    • General
• Character Controllers
  • Introduction
  • Kinematic Character Controller
  • Creating a character controller
  • Overlap Recovery Module
  • Character Volume
  • Volume Update
  • Moving a Character Controller
  • Graphics Update
  • Auto Stepping
  • Climbing Mode
  • Up Vector
  • Walkable Parts & Invisible Walls
  • Obstacle Objects
  • Hit Callback
  • Behavior Callback
  • Character Interactions: CCT-vs-dynamic actors
  • Character Interactions: CCT-vs-CCT
  • Hidden Kinematic Actors
  • Time Stepping
  • Invalidating Internal Geometry Caches
  • Runtime Tessellation
  • Troubleshooting
    • Character goes through walls in rare cases
    • Tessellation performance issue
    • The capsule controller manages to climb over obstacles higher than the step offset value
• Debug Visualization
  • Introduction
  • Usage
• PhysX Visual Debugger (PVD)
  • PVD
  • Basic Setup (SDK Side)
    • Network Setup
    • File Setup
  • Advanced Setup
    • Connection Flags
    • Visualizing Externals and Extended Data
    • Visualizing SceneQuery
    • Custom PvdClient
    • PVD Error Stream
    • Custom profiling
• Simulation Statistics
  • Interface
  • Usage
• Serialization
  • Introduction
  • First Code
  • In-depth Discussion
    • Collections
    • Serializing Complete Collections
    • Serializing Incomplete Collections
    • Reference Counting of Deserialized Objects
    • Reconnecting PhysX and Application-Objects
    • Serializing Everything
    • Serializability
    • Binary Serialization Specifics
    • API-level Serialization (RepX) Specifics
  • Common Use Cases
  • Snippet Discussion
    • SnippetSerialization
    • SnippetConvert
    • SnippetLoadCollection
  • Best practices / Troubleshooting
  • PVD
• Extending Serialization
  • Introduction
  • Overview
  • Binary Serialization of Custom Classes
  • RepX Serialization of Custom Classes
    • PhysX API Metadata System
• Best Practices Guide
  • Introduction
  • Debugging
    • Use checked builds and the error stream
    • Visualizing physics data
    • Visualizing physics data (2)
    • Limiting coordinates
  • Performance Issues
    • Use profile builds to identify performance bottlenecks
    • Use release builds for final performance tests
    • Disable debug visualization in final/release builds
    • Debug visualization is very slow
    • Consider using tight bounds for convex meshes
    • Use scratch buffers
    • Use the proper mid-phase algorithm
    • Use the proper narrow-phase algorithm
    • Use the proper broad-phase algorithm
    • Use the scene-query and simulation flags
    • Tweak the dynamic tree rebuild rate
    • Use the insertion callback when cooking at runtime
    • Kill kinematic pairs early
    • Beware of PxScene::getActors()
    • The "Well of Despair"
    • Pruner Performance for Streamed Environments
    • Performance Implications for Multi-Threading
    • Memory allocation
  • Character Controller Systems using Scene Queries and Penetration Depth Computation
  • Quantizing HeightField Samples
  • Reducing memory usage
    • Consider using tight bounds for convex meshes
    • Use scratch buffers
    • Flush simulation buffers
    • Use preallocation
    • Tweak cooking parameters
    • Share shape and mesh data
    • Use the scene-query and simulation flags
    • Kill kinematic pairs early
  • Behavior issues
    • Objects do not spin realistically
    • Overlapping objects explode
    • Rigid bodies are jittering on the ground
    • Piles or stacks of objects are not going to sleep
    • Jointed objects are unstable
  • GPU Rigid Bodies
  • Determinism
• Migrating From PhysX SDK 2.x to 3.x
  • Removed Features
    • Compartments
    • Deformables
    • NxUtilLib
    • Anisotropic Friction
  • Basics
    • SDK Header
    • SDK Redistribution
    • API Conventions
    • Callback Classes
    • Memory Management
    • Debug Rendering
    • Error Reporting
    • Type Casting
    • Multithreading
    • Startup and Shutdown
    • Extensions
    • Heightfields
    • Cooking
    • Serialization
  • API Design Changes
    • Changed Actor Hierarchy
    • Actor Creation
  • Material Indexes
  • Continuous Collision Detection
  • Pose Description
  • Shape Description
    • Skin Width
  • Joints
  • Time Stepping
    • Simulation Parameters
  • Collision Filtering
  • Scene Queries
    • Raycasts
    • Overlaps
    • Sweep Tests
• Migrating From PhysX SDK 3.2 to 3.3
  • Math Classes
  • Scene Query API
  • SPU batch queries
  • Core PhysX
  • PhysX Extensions
  • PhysX Character Controller
  • PhysX Vehicles
  • CCD
  • PhysX Visual Debugger
  • PhysX Cloth
  • RepX Serialization
  • Binary Serialization
  • PhysX TaskManager
• Migrating From PhysX SDK 3.3 to 3.4
  • Deprecated APIs
    • PxRigidActor::createShape
    • PxSceneFlag::eDEPRECATED_TRIGGER_TRIGGER_REPORTS
    • PhysX particles
  • Core PhysX
  • Contact Generation
  • PhysX Cooking
  • Reference Counting
  • PhysX Visual Debugger
  • Scene queries
  • PxExtensions
• Migrating From PhysX SDK 3.4 to 4.0
  • Deprecated APIs
  • PhysX particles
  • PhysX clothing
  • PhysX distribution
    • CMake build
    • PxShared
  • Core PhysX
  • PhysX Extensions