Apex render data is stored in a vertex buffer accessible through the VertexBuffer interface. This vertex buffer supports a wide variety of attributes, and it also supports a variety of formats for each attribute. A format descriptor for the entire buffer is accessible through the VertexFormat interface.
Although every vertex attribute (for example position, normal, etc.) may be given any format (for example float[3], byte[3], etc.), there are some restrictions imposed by the framework and individual modules. There are two overall (framework) restrictions:
See the individual module documentation for further per-module restrictions.
One authors an apex render mesh by creating an authoring object with the ApexSDK::createRenderMeshAsset function. This object uses the RenderMeshAssetAuthoring interface.
Apex render mesh assets are built by filling in a descriptor, RenderMeshAssetAuthoring::MeshDesc. See RenderMeshAsset.h. This descriptor is simply an array of “submesh” descriptors, of type RenderMeshAssetAuthoring::SubmeshDesc. Submeshes correspond to individual materials, or shaders, or other render state. The idea is that a submesh can be drawn (ideally) in one draw call.
The SubmeshDesc is set up so that you can point its fields directly to your mesh data, with minimal (or no) need to convert it into an intermediate format.
The SubmeshDesc contains contains an array of VertexBuffer objects, which just contain format descriptors and pointers to your data. You set these pointers using RenderMeshAssetAuthoring::VertexBuffer::setSemanticData(...):
PX_INLINE void setSemanticData(RenderVertexSemantic::Enum semantic, const void *data, physx::PxU32 stride, RenderDataFormat::Enum format, RenderDataFormat::Enum srcFormat = RenderDataFormat::UNSPECIFIED)
The first argument, semantic, is the data channel you are setting. For example, this may be the vertex position, normal, tangent, uv coordinate, etc. The possible “standard semantics” are given below.
| Semantic (RenderVertexSemantic::Enum) | Meaning |
| POSITION | Position of vertex |
| NORMAL | Normal at vertex |
| TANGENT | Tangent at vertex |
| BINORMAL | Binormal at vertex |
| COLOR | Color at vertex |
| TEXCOORD0 | Texture coord 0 of vertex |
| TEXCOORD1 | Texture coord 1 of vertex |
| TEXCOORD2 | Texture coord 2 of vertex |
| TEXCOORD3 | Texture coord 3 of vertex |
| BONE_INDEX | Bone index of vertex |
| BONE_WEIGHT | Bone weight of vertex |
Only these semantics may be set with the setSemanticData function, and only one data channel per semantic is allowed. The data buffer pointer is passed in as a void* pointer in data. The stride field gives the byte difference between one data element and the next. The format field is the format you wish to store the data in, in the created render mesh. If this is same format as the source data (pointed to by data), then you may leave the last parameter at its default. If the source data is a different format, you must specify this format in the last parameter.
The allowed formats are given in RenderDataFormat::Enum (see RenderDataFormat.h). These formats are shown below.
| Format (RenderDataFormat::Enum) | Meaning |
| UNSPECIFIED | No format (semantic not used) |
| UBYTE1 | One unsigned 8-bit integer (PxU8[1]) |
| UBYTE2 | Two unsigned 8-bit integers (PxU8[2]) |
| UBYTE3 | Three unsigned 8-bit integers (PxU8[3]) |
| UBYTE4 | Four unsigned 8-bit integers (PxU8[4]) |
| USHORT1 | One unsigned 16-bit integer (PxU16[1]) |
| USHORT2 | Two unsigned 16-bit integers (PxU16[2]) |
| USHORT3 | Three unsigned 16-bit integers (PxU16[3]) |
| USHORT4 | Four unsigned 16-bit integers (PxU16[4]) |
| SHORT1 | One signed 16-bit integer (PxI16[1]) |
| SHORT2 | Two signed 16-bit integers (PxI16[2]) |
| SHORT3 | Three signed 16-bit integers (PxI16[3]) |
| SHORT4 | Four signed 16-bit integers (PxI16[4]) |
| UINT1 | One unsigned integer (PxU32[1]) |
| UINT2 | Two unsigned integers (PxU32[2]) |
| UINT3 | Three unsigned integers (PxU32[3]) |
| UINT4 | Four unsigned integers (PxU32[4]) |
| R8G8B8A8 | Four unsigned bytes (PxU8[4]) representing red, green, blue, alpha |
| B8G8R8A8 | Four unsigned bytes (PxU8[4]) representing blue, green, red, alpha |
| R32G32B32A32_FLOAT | Four floats (PxF32[4]) representing red, green, blue, alpha |
| B32G32R32A32_FLOAT | Four floats (PxF32[4]) representing blue, green, red, alpha |
| BYTE_UNORM1 | One unsigned normalized value in the range [0,1], packed into 8 bits (PxU8[1]) |
| BYTE_UNORM2 | Two unsigned normalized value in the range [0,1], each packed into 8 bits (PxU8[2]) |
| BYTE_UNORM3 | Three unsigned normalized value in the range [0,1], each packed into bits (PxU8[3]) |
| BYTE_UNORM4 | Four unsigned normalized value in the range [0,1], each packed into 8 bits (PxU8[4]) |
| SHORT_UNORM1 | One unsigned normalized value in the range [0,1], packed into 16 bits (PxU16[1]) |
| SHORT_UNORM2 | Two unsigned normalized value in the range [0,1], each packed into 16 bits (PxU16[2]) |
| SHORT_UNORM3 | Three unsigned normalized value in the range [0,1], each packed into 16 bits (PxU16[3]) |
| SHORT_UNORM4 | Four unsigned normalized value in the range [0,1], each packed into 16 bits (PxU16[4]) |
| BYTE_SNORM1 | One signed normalized value in the range [-1,1], packed into 8 bits (PxU8[1]) |
| BYTE_SNORM2 | Two signed normalized value in the range [-1,1], each packed into 8 bits (PxU8[2]) |
| BYTE_SNORM3 | Three signed normalized value in the range [-1,1], each packed into bits (PxU8[3]) |
| BYTE_SNORM4 | Four signed normalized value in the range [-1,1], each packed into 8 bits (PxU8[4]) |
| SHORT_SNORM1 | One signed normalized value in the range [-1,1], packed into 16 bits (PxU16[1]) |
| SHORT_SNORM2 | Two signed normalized value in the range [-1,1], each packed into 16 bits (PxU16[2]) |
| SHORT_SNORM3 | Three signed normalized value in the range [-1,1], each packed into 16 bits (PxU16[3]) |
| SHORT_SNORM4 | Four signed normalized value in the range [-1,1], each packed into 16 bits (PxU16[4]) |
| HALF1 | One 16-bit floating point value |
| HALF2 | Two 16-bit floating point values |
| HALF3 | Three 16-bit floating point values |
| HALF4 | Four 16-bit floating point values |
| FLOAT1 | One 32-bit floating point value |
| FLOAT2 | Two 32-bit floating point values |
| FLOAT3 | Three 32-bit floating point values |
| FLOAT4 | Four 32-bit floating point values |
| FLOAT3x4 | A 3x4 matrix (see PxMat34) |
| FLOAT3x3 | A 3x3 matrix (see PxMat33) |
| FLOAT4_QUAT | A quaternion (see PxQuat) |
| BYTE_SNORM4_QUATXYZW | A normalized quaternion with signed byte elements, X,Y,Z,W format (PxU8[4]) |
| SHORT_SNORM4_QUATXYZW | A normalized quaternion with signed short elements, X,Y,Z,W format (PxU16[4]) |
Source and destination formats may be different only if a conversion is defined between the formats. Currently, these conversions are defined:
If you wish to supply other data channels, you may create an array of custom buffer descriptors (RenderMeshAssetAuthoring::VertexBuffer::RenderSemanticData) and pass them into RenderMeshAssetAuthoring::VertexBuffer::setCustomSemanticData(...).
When possible, however, use the standard semantics so that APEX modules which might rely on the data can interpret it correctly. For example, positions should always use the RenderVertexSemantic::POSITION semantic, as many modules rely on vertex positions for various calculations.
In addition, you supply the mesh’s index buffer in the SubmeshDesc. Currently only triangle primitives (no strips or fans) are supported. If you partition your index buffer(s) into disjoint parts, you can use the SubmeshDesc’s m_partIndices array to specify this partition. The RenderMesh interface allows the user to set visibility on part subsets of the mesh. Note: it is required that the vertex buffer also be similarly partitioned by parts, but this is not enforced in the user’s data. The authoring function will sort the APEX render mesh’s vertex buffer to meet this requirement, however. This means that the final vertex indices may not correspond to your original indices. In order to map the vertices back to your original ordering, you may create a mapping buffer as described below.
The RenderMeshAssetAuthoring::createRenderMesh(...) function takes the MeshDesc descriptor and builds an APEX render mesh asset from it. Its second parameter is the createMappingInformation bool. If this is set to TRUE, then a custom buffer named “VERTEX_ORIGINAL_INDEX” (see VertexBuffer Interface) will be created which is is the original index in the MeshDesc for each vertex. The only time the vertices will be rearranged is when they are made into contiguous parts. There is no further cooking of the mesh data, for example to reduce the vertex buffer by eliminating redundant vertices.
If you wish to reduce your vertex buffer by eliminating redundant vertices, the RenderMeshAssetAuthoring API provides a helper function to do this called createReductionMap(...). It only gives you a map by which you may reduce your vertex data. It will not modify your vertex data for you.
Once you have called RenderMeshAssetAuthoring::createRenderMesh, this authoring class may be used to create an RenderMeshAsset using the standard authorable asset functions (see Loading Assets).
Once you have created an APEX render mesh, you may access it through the RenderMeshAsset interface. This interface gives you the mesh broken into submeshes via the RenderMeshAsset::getSubmesh method. This method returns an RenderSubmesh interface. Through that, you can access the mesh’s vertex buffer using RenderSubmesh::getVertexBuffer, which returns an VertexBuffer interface.
The VertexBuffer interface gives you access to the render data, and also allows conversion between render data formats. Every RenderSubmesh has this interface.
The number of vertices is returned by this function:
virtual physx::PxU32 getVertexCount() const = 0;
The format of the vertices is returned by this function:
virtual const VertexFormat& getFormat() const = 0;
This returns an VertexFormat interface, described below, in VertexFormat Interface .
The VertexFormat interface will give you a buffer index for any data channel (semantic or custom data) in the buffer. You may then use that index to access the buffer, using
virtual const void* getBuffer( physx::PxU32 bufferIndex ) const = 0;
The data is returned as a void*, which you must cast appropriately based upon the data format (also obtained from the VertexFormat interface). Both of these operations may be done at once using
virtual const void* getBufferAndFormat( RenderDataFormat::Enum& format, physx::PxU32 bufferIndex ) const = 0;
Finally, there is a utility which will fill a user buffer with render buffer data, and even convert between the render data format and a destination format specified by the user, if that conversion exists. You may also specify a subset of the buffer to copy, using the startVertexIndex and elementCount fields.
virtual bool getBufferData( void* buffer, physx::RenderDataFormat::Enum bufferFormat, physx::PxU32 bufferIndex,
physx::PxU32 startVertexIndex, physx::PxU32 elementCount ) const = 0;
Note, regardless of the value of startVertexIndex, the buffer will always be filled starting at the buffer’s beginning. Also note, you may find the size of an element in any format using the function
RenderDataFormat::getFormatDataSize( RenderDataFormat::Enum format );
This interface accompanies the VertexBuffer interface and may be accessed through VertexBuffer::getFormat.
The various semantics and custom buffers formats, as well as their buffer index (used to retrieve the buffer data using VertexBuffer::getBuffer), are all looked up by a unique buffer ID. This ID is a hash of the buffer name. For a custom buffer, this name is specified by the user. For a standard semantic (RenderVertexSemantic::Enum), this name may be looked up using
virtual const char* getSemanticName( RenderVertexSemantic::Enum semantic ) const = 0;
Whatever the name, the buffer ID may be looked up using
virtual BufferID getID( const char* name ) const = 0;
In addition there is the shortcut function for semantics,
virtual BufferID getSemanticID( RenderVertexSemantic::Enum semantic ) const = 0;
This buffer ID will not change, and so may be serialized, cached, etc. To find a buffer index use
virtual physx::PxI32 getBufferIndexFromID( BufferID id ) const = 0;
All of the format accessors, as well as the VertexBuffer accessors, use this index. Note, this index is volitile. If you add or remove semantics or custom buffers, the index may change.
There are basically three pieces of information associated with each buffer: format, access type, and serialization.
The buffer’s format is enumerated using RenderDataFormat::Enum, and is the data layout. This is accessed using:
virtual RenderDataFormat::Enum getBufferFormat( physx::PxU32 index ) const = 0;
The buffer’s access type is a hint regarding how the data will be accessed. There are three types, enumerated by RenderDataAccess::Enum. These are STATIC, DYNAMIC, and STREAMING. STATIC buffers are only sent to the application once. DYNAMIC and STREAMING buffers are sent every frame.
Use
virtual RenderDataAccess::Enum getBufferAccess( physx::PxU32 index ) const = 0;
for the access type.
Finally, you can query a buffer to see whether it will get serialized, using
virtual bool getBufferSerialize( physx::PxU32 index ) const = 0;
Corresponding set functions, as well as the rest of the VertexFormat API is documented in the APEX Framework API section.