NVIDIA PhysX SDK 3.3.4 Documentation User's Guide翻译 --The PhysX API

The PhysX API
物理运算引擎API


Introduction
介绍


This chapter covers the basic patterns common to the PhysX application programming interface (API).
本章涵盖了基本模式常见的物理运算引擎应用程序编程接口(API)。


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.
我们致力于保持这个API稳定和向后兼容从一个较小的版本下,保护投资你的集成代码。


The PhysX API is composed primarily of abstract interface classes.
物理运算引擎API是由主要的抽象接口类。


Classes, enumerations and functions defined by the API have the prefix Px.
类、枚举和函数定义的API有前缀Px。


Note There is currently one section of the public API which does not have the Px prefix: the PhysX Visual Debugger connection library which has the prefix Pvd.
注意目前公共API的一部分没有Px前缀:物理运算引擎可视化调试器连接库前缀Pvd。


The PhysX libraries also expose some classes and functions that are not part of the public API.
物理运算引擎库也暴露一些类和函数不公共API的一部分。


These are primarily containers and platform abstractions that are required to build the PhysX libraries which are distributed as source, and are also used in the samples.
这些主要是容器和所需平台抽象构建分布式的物理运算引擎库源,也是使用的样本。


They can be recognized because they do not have the Px prefix.
他们可以被识别,因为他们没有Px前缀。


Even though they are in principle accessible to users, they are largely undocumented and we do not maintain compatibility of this code between PhysX versions.
即使他们原则上可以被用户访问,他们基本上是不被记录，而且我们不维护这段代码同物理运算引擎版本之间的兼容性的。


For that reason we recommend strongly against their use in applications.
因此我们强烈建议不要再应用程序中使用他们。


Memory Management¶
内存管理¶


PhysX performs all allocations via the PxAllocatorCallback interface.
物理运算引擎通过PxAllocatorCallback接口执行所有的分配。


You must implement this interface in order to initialize PhysX:

为了初始化物理运算引擎，您必须实现这个接口:

class PxAllocatorCallback
{
public:
    virtual ~PxAllocatorCallback() {}
    virtual void* allocate(size_t size, const char* typeName, const char* filename,
        int line) = 0;
    virtual void deallocate(void* ptr) = 0;
};

The size of the request is specified in bytes, and PhysX requires that the memory that is returned be 16-byte aligned.
请求的大小用字节数指定,而且物理运算引擎要求的内存返回是以16字节对齐的。


On many platforms malloc() returns memory that is 16-byte aligned, and on Windows the system function _aligned_malloc() provides this capability.
在许多平台上malloc()返回16字节对齐的内存,而在Windows系统函数要使用_aligned_malloc()才提供了此功能。


The other parameters to allocate() are a string which identifies the type of allocation, and the __FILE__ and __LINE__location inside PhysX code where the allocation was made.
allocate()的其他参数是一个字符串（标识分配的类型）,而参数__FILE__和 __LINE__location内置在物理运算引擎代码分配。（这部分有些不好）


Refer to PxAllocatorCallback::allocate() to find out more about them.
关于这部分更多信息，可以参考PxAllocatorCallback::allocate()来获取到。


A simple implementation of the error callback class can be found in the PhysX Extensions library, see class PxDefaultAllocatorCallback.
在物理运算引擎扩展库，查看PxDefaultAllocatorCallback可以找到错误回调类的一个简单实现。


Note On some platforms PhysX uses system library calls to determine the correct type name, and the system function that returns the type name may call the system memory allocator.
注意：在一些平台上，物理运算引擎使用系统库调用来确定正确的类型名称，还使用系统函数返回类型名称，这些类型名称可以调用系统内存分配器。


If you are instrumenting system memory allocations, you may observe this behavior.
如果使用的是系统内存分配,就可以观察到这种行为。


To prevent PhysX requesting type names, disable allocation names using the methodPxFoundation::setReportAllocationNames().
为了防止物理运算引擎请求类型名称,使用methodPxFoundation::setReportAllocationNames()的时候禁用分配名称。


You can place PhysX objects in memory owned by the application using PhysX' binary deserialization mechanism.
通过使用PhysX的二进制反序列化机制，您可以将物理运算引擎对象在应用所拥有的内存中使用，。


See Serialization for details.
关于这部分详细信息,请参阅序列化。


As an alternative to instrumenting the allocator, you can obtain detailed information about memory allocation in the PhysX Visual Debugger
作为插装分配器的替代,在物理运算引擎可视化调试器一节您可以获得关于内存分配的详细的信息。

(see: PhysX Visual Debugger (PVD))

-------------------以下内容因为提示不是亟需，所以暂时放置在这里-----------

..
. .


note:: the following section does not really belong here now, rather it should be in the chapter on performance tuning.
注:以下部分并不真的属于这里，而是应该在性能调优的一章出现。


Minimizing dynamic allocation is an important aspect of performance tuning, and PhysX provides several mechanisms to control memory usage.
最小化性能调优的动态分配是一个重要的方面,和物理运算引擎提供了一些机制来控制内存使用。


Reduce allocation used for tracking objects by presizing the capacities of scene data structures, using either PxSceneDesc::limits before creating the scene or the function PxScene::setLimits().
减少分配用于跟踪对象presizing场景数据结构的能力,使用PxSceneDesc:限制在创建场景之前或函数PxScene::setLimits()。


When resizing, the new capacities will be at least as large as required to deal with the objects currently in the scene.
调整时,新的能力将至少一样大需要处理的对象目前在现场。


These values are only for preallocation and do not represent hard limits, so if you add more objects to the scene than the capacity limits you have set, PhysX will allocate more space.
这些值仅为预先配置,不代表硬限制,所以如果你添加更多的对象比你设定的容量限制,现场物理运算引擎将分配更多的空间。


Much of the memory PhysX uses for simulation is held in a pool of blocks, each 16K in size.
模拟内存物理运算引擎使用的是在一个块池举行,每16 k大小。


You can control the current and maximum size of the pool with the nbContactDataBlocks and maxNbContactDataBlocks members of PxSceneDesc.
你可以控制当前和线程池的最大大小,与nbContactDataBlocks maxNbContactDataBlocks PxSceneDesc的成员。


PhysX will never allocate more than the maximum number of blocks specified, and if there is insufficient memory it will instead simply drop contacts or joint constraints.
物理运算引擎不会超过指定的最大数量的块分配,如果没有足够的内存将简单地删除联系人或共同约束。


You can find out how many blocks are currently in use with the getNbContactBlocksUsed() method, and find out the maximum number that have ever been used with the getMaxNbContactDataBlocksUsed() method.
你能找出多少块目前正在使用getNbContactBlocksUsed()方法,并找出曾经使用的最大数量与getMaxNbContactDataBlocksUsed()方法。


Use PxScene::flushSimulation() to reclaim unused blocks, and to shrink the size of scene data structures to the size presently required.
使用PxScene::flushSimulation()来回收未使用的块,并缩小场景数据结构的大小目前所需的大小。


To reduce temporary allocation performed during simulation, provide physx with a memory block in the simulate() call.
减少临时分配期间执行模拟,为物理运算引擎提供的内存块模拟()调用。


The block may be reused by the application after the fetchResults() call which marks the end of simulation.
块可能是由应用程序重用fetchResults后()调用,标志着仿真的结束。


The size of the block must be a multiple of 16K, and it must be 16-byte aligned.
块的大小必须16 k的倍数,并且必须是16字节对齐的。

Error Reporting¶
错误报告¶


PhysX logs all error messages through the PxErrorCallback interface.
物理运算引擎使用PxErrorCallback接口以日志形式输出的所有错误消息。


You must implement this interface in order to initialize PhysX:
为初始化物理运算引擎，您必须实现这个接口,










There is only a single function to implement, reportError.
只需要实现有一个函数reportError。


This function should log the passed message, or print it on the application's output console.
这个函数应该以日志记录传递的消息,或者在应用程序输出控制台打印出来。


For the more serious error codes eABORT, eINVALID_PARAMETER, eINVALID_OPERATION, eINTERNAL_ERROR andeOUT_OF_MEMORY, breaking into the debugger may be a more appropriate choice.
关于可以中断调试器的其他更严重的错误代码eABORT、eINVALID_PARAMETER eINVALID_OPERATION,eINTERNAL_ERROR 和 eOUT_OF_MEMORY,可以提供更多合适的选择。


Whatever you do, do not just ignore the messages.
无论你做什么,不要忽略这些消息。


A simple implementation of the error callback class can be found in the PhysX Extensions library, see class PxDefaultErrorCallback.
在物理运算引擎扩展库，查看类PxDefaultErrorCallback可找到错误回调类的一个简单的实现,。

Error Reporting¶
错误报告¶


PhysX logs all error messages through the PxErrorCallback interface.
物理运算引擎使用PxErrorCallback接口以日志形式输出的所有错误消息。


You must implement this interface in order to initialize PhysX:
为初始化物理运算引擎，您必须实现这个接口,

class UserErrorCallback : public PxErrorCallback
{
public:
    virtual void reportError(PxErrorCode::Enum code, const char* message, const char* file,
        int line)
    {
        // error processing implementation
        ...
    }
};

There is only a single function to implement, reportError.
只需要实现有一个函数reportError。


This function should log the passed message, or print it on the application's output console.
这个函数应该以日志记录传递的消息,或者在应用程序输出控制台打印出来。


For the more serious error codes eABORT, eINVALID_PARAMETER, eINVALID_OPERATION, eINTERNAL_ERROR andeOUT_OF_MEMORY, breaking into the debugger may be a more appropriate choice.
关于可以中断调试器的其他更严重的错误代码eABORT、eINVALID_PARAMETER eINVALID_OPERATION,eINTERNAL_ERROR 和 eOUT_OF_MEMORY,可以提供更多合适的选择。


Whatever you do, do not just ignore the messages.
无论你做什么,不要忽略这些消息。


A simple implementation of the error callback class can be found in the PhysX Extensions library, see class PxDefaultErrorCallback.
在物理运算引擎扩展库，查看类PxDefaultErrorCallback可找到错误回调类的一个简单的实现,。

Math Classes
数学类


The common math classes used in PhysX are PxVec2, PxVec3, PxVec4, PxMat33, PxMat44, PxTransform, PxPlane and PxQuat, which are are defined in their respective header files, e.g. .
在PhysX中使用的常见数学类是PxVec2,PxVec3,PxVec4,PxMat33,PxMat44,PxTransform,PxPlane 和PxQuat。它们在各自的头文件中被定义,例如(SDKRoot)/Include/foundation/PxVec3.h。


The types support standard operator overloads and typical math operations.
支持类型的标准运算符重载和典型的数学操作。


Zero and identity objects where appropriate can be constructed by passing the argumentsPxZero and PxIdentity respectively.
可以分别通过argumentsPxZero和PxIdentity构造应该出现在适当的地方的零和标识对象。


Some points to note are:
需要注意有以下几点:


PxTransform is a representation of a rigid body transform as a rotation quaternion and a position vector, and PhysX functions which take transforms all use this type.
PxTransform用旋转四元数和位置矢量表示刚体变换,和PhysX的变换函数都使用这种类型。


PxPlane is a homogeneous plane equation: that is, the constructor PxPlane(n, d) represents the equation n.
PxPlane是一个齐次平面方程:构造函数PxPlane(n,d）实现了这个方程。


x + d = 0.
x + d = 0。


PxMat33 and PxMat44 matrices represent transformations with basis vectors in the columns (pre-multiply with matrix on the left hand side) and are stored in column-major order.
用列(pre-multiply和矩阵左边)的基向量，PxMat33 和PxMat44矩阵表达了这样的转换。  PxMat33 和PxMat44矩阵以列为主的秩序进行存储。


This format is layout compatible with popular graphics APIs such as OpenGL and Direct3D.
这种格式是同OpenGL和Direct3D等流行的图形api布局兼容的。


For example, to set the model transformation for a rigid body in OpenGL:
例如,在OpenGL中，设置刚体模型转换为:

// retrieve world space transform of rigid body
PxTransform t = rigidActor.getGlobalPose();

// convert to matrix form
PxMat44 m = PxMat44(t);

// set to OpenGL
glMatrixMode(GL_MODELVIEW);
glPushMatrix();

// PxMat44::front() returns a pointer to the first matrix element
glMultMatrixf(m.front());

// draw model

glPopMatrix()

DirectX uses row-major storage for matrices by default (D3DMATRIX), but also stores basis vectors in rows (post-multiply on the right), so PxMat44 may be used in place of D3DXMATRIX types directly.
DirectX默认使用行存储矩阵(D3DMATRIX),而且在行(post-multiply右边)存储基向量,所以PxMat44可以直接代替D3DXMATRIX类型。


Connecting PhysX Objects with User Application Objects¶
¶用户应用程序对象连接物理运算引擎对象


Often an application needs to associate PhysX objects with application objects for game logic or rendering purposes.
为实现游戏逻辑或渲染的目的，通常应用程序需要将物理运算引擎对象与应用程序对象实现关联。


An easy way to connect a single user application object with a PhysX object is to use the userData member provided by the most important PhysX classes (PxActor::userData, PxShape::userData, PxMaterial::userData, ...).
一种连接一个用户应用程序对象与物理运算引擎对象的简单的方式来是使用userDat成员所提供的最重要的物理运算引擎类(PxActor::userData, PxShape::userData, PxMaterial::userData, ...)。


The userData member is a void* pointer which is reserved for application use.
userData成员是一个留给应用程序使用的void *指针。


Each class only has one userData field, so to manage multiple associations another mechanism must be used.
每个类只有一个userData字段,所以必须使用另一种机制管理多种联系。


Type Casting
类型映射


PhysX API interface classes inherit from a top-level interface called PxBase, which provides mechanisms for type-safe down-casting between interface types.
物理运算引擎API接口类继承一个叫做PxBase顶级接口,它在接口类型之间提供了类型安全映射的机制。


For example, to cast from a PxActor to a PxRigidDynamic, use the following idiom:
例如,将从PxActor PxRigidDynamic的映射,使用下面的习惯用法:

PxActor* actor = <...>
PxRigidDynamic* myActor = actor->is<PxRigidDynamic>();

const PxActor* actor = <...>
const PxRigidDynamic* myActor = actor->is<PxRigidDynamic>();

This pattern can be used to cast to intermediate types in the hierarchy such as PxRigidActor, but this is somewhat slower than casting to concrete types.
此模式可以用于映射中间类型在层次结构例如PxRigidActor,但这有点慢于映射具体类型。


In addition, PxBase provides the following capabilities:
此外,PxBase提供了以下功能:


getConcreteType() provides an integer value which corresponds to the concrete type of an object
getConcreteType()提供了一个与对象的具体类型对应的整数值


getConcreteTypeName() provides a string name of the concrete type
getConcreteTypeName()提供了一个具体类型的字符串名称


isKindOf() provides string-based testing of inheritance
isKindOf()提供了基于字符串测试的继承


Reference Counting
引用计数


Some PhysX objects are designed to be shared and referenced multiple times in a  scene graph.
有些PhysX对象在PhysX的场景图中，被设计为共享和多次引用。


For example, a PxConvexMeshmay be referenced by multiple PxShape objects, each sharing the same geometry but associated with different actors.
例如,一个PxConvexMeshmay由多个PxShape对象引用,每个都共享和不同的角色相关的相同的几何。


The specific types are PxTriangleMesh, PxHeightField, PxConvexMesh, PxMaterial, PxClothFabric, and PxShape.
这些特定类型有PxTriangleMesh,PxHeightField、PxConvexMesh PxMaterial,PxClothFabric和PxShape。


Each object of these types has a reference count.
这些类型的每个对象有一个引用计数。


The rules for reference counting are as follows:
引用计数的规则如下:


when an object is created from PxPhysics, it has a reference count of 1.
从PxPhysics创建一个对象时,它有一个引用计数为1。


when an object's reference count reaches 0, the object is destroyed.
当这个对象的引用计数达到0,这个对象被摧毁。


when a new counted reference is created, the reference count is incremented.
当创建一个新的计算引用,引用计数增加。


Counted references are as follows:
计算参考如下:


when a PxShape references a PxConvexMesh, PxHeightfield, or PxTriangleMesh.
当一个PxShape引用PxConvexMesh、PxHeightfield或PxTriangleMesh。


when a PxShape references a PxMaterial.
当一个PxMaterial PxShape引用。


when a PxRigidActor references a PxShape.
当一个PxShape PxRigidActor引用。


when a PxCloth references a PxClothFabric.
当一个PxClothFabric PxCloth引用。


when a counted reference is destroyed, or the object's release() method is called, the reference count is decremented.
当计算参考被摧毁,或对象的释放()方法被调用时,引用计数递减。


when an object is created through deserialization, its reference count is 1, plus the number of counted references that exist to the object.
当对象通过反序列化对象创建时,它的引用计数是1,加上存在的对象的引用数量。

-----以下部分简单处理----

The initial reference count of 1 ensures the object is not destroyed until the application allows it by calling release() - thereafter it will be destroyed when no remaining counted references to it exist.

最初的引用计数1确保对象不是毁灭,直到应用程序允许它通过调用释放()——之后它将被摧毁时不存在剩余数引用它。

For example, if you create a shape using PxPhysics::createShape() and attach it to an actor with PxRigidActor::attachShape(), it has a reference count of 2.

例如,如果您使用PxPhysics:创建一个形状:createShape()和将它附加到一个演员PxRigidActor::attachShape(),它有一个引用计数为2。

If you then call the shape's release() method, it has a reference count of 1.

如果你然后调用形状的释放()方法,它有一个引用计数为1。

When the actor is destroyed, or the shape is detached from the actor, the reference count is decremented, and since it is now 0, the shape is destroyed.

当演员被摧毁,或形状是脱离演员,引用计数递减,因为它现在是0,形状被摧毁。

Note subtypes of PxGeometry do not have counted references to the meshes to which they point, e.g. whenPxConvexMeshGeometry points to a PxConvexMesh.

注意亚型PxGeometry没有计算的网格点的引用,例如whenPxConvexMeshGeometry PxConvexMesh点。

A counted reference exists only when the geometry is within a PxShape.

只有当存在着计算参考几何是PxShape内。

Note shapes are often created using the utility method PxActor::createShape().

注意形状通常使用实用程序创建的方法PxActor::createShape()。

Take special care when deserializing such actors (see Shapes and Reference Counting of Deserialized Objects)

要特别注意当演员这样的反序列化(见形状和反序列化对象的引用计数)

Using Different Units

使用不同的单位

PhysX is designed to produce correct results regardless of the units of length or mass, so long as inputs use those units consistently.

物理运算引擎旨在生成正确的结果不管的单位长度或质量,只要输入使用这些单位一致。

However, there are certain tolerances values whose defaults need to be adjusted depending on the units. 

然而,有一些公差值的默认值根据单位需要调整。

In order to ensure that these tolerances default to reasonable values, adjust the values in PxTolerancesScale when creating the PxPhysics and PxCooking interfaces.

为了确保这些公差默认值,合理调整值PxTolerancesScale创建PxPhysics时和PxCooking接口。

Tolerances for objects are set at creation time, and may then be overridden by the application.

公差的对象在创建时设置,应用程序可能会被覆盖。

You should set tolerances based on the typical size of objects in your simulation.

你应该设定公差基于模拟对象的典型的大小。

For example, if you are working with objects of size approximately one meter, but in units of centimeters, you should set the scale as follows:

例如,如果您正在与对象的大小约1米,但以厘米为单位,你应该设定范围如下:

PxTolerancesScale scale;
scale.length = 100;        // typical length of an object
scale.speed = 981;         // typical speed of an object, gravity*1s is a reasonable choice
PxPhysics *p = PxCreatePhysics(PX_PHYSICS_VERSION, scale, ...);

This will result in the defaults for values like PxShape::contactDistance being scaled appropriately for your objects.

这将导致违约等价值观PxShape:对象:contactDistance比例适当。

You can also set the typical object mass in PxTolerancesScale.

您还可以设置典型对象在PxTolerancesScale质量。

It is important to use the same PxTolerances value for initialization of PxCooking and PxPhysics, and also when creating PxSceneDescobjects.

重要的是要使用相同的PxTolerances值初始化PxCooking PxPhysics,以及创建PxSceneDescobjects时。

Assertions

断言

PhysX uses the PX_DEBUG macro to enable or disable assertions.

物理运算引擎使用PX_DEBUG宏启用或禁用断言。

This macro is not set in the PhysXCore and PhysXCommon libraries, and so by default these libraries will not trigger assertions, however you may configure the libraries provided as source to enable them.

这个宏PhysXCore和PhysXCommon库没有设置,因此默认情况下这些库不会触发断言,然而你可以配置库作为源,使他们提供。

When an assert is triggered, PhysX calls an assert handler.

当触发一个断言是,物理运算引擎调用一个断言处理程序。

By default the assert handler will trigger a debug breakpoint.

默认情况下,维护处理程序将触发一个调试断点。

However, you may call the function PxSetAssertHandler() to customize the assert handler.

然而,你可以叫PxSetAssertHandler()函数来定制维护处理程序。