MaxSDK::Graphics::ViewportInstancing Namespace Reference

This API is about having a single INode in the scene, but having many geometries being instantiated at the GPU level in the viewport when the INode is drawn, e.g : a particles system. More...

Classes
struct	InstanceData
	The struct InstanceData is used to pass instance data to different methods of the InstanceDisplayGeometry class. More...
class	InstanceDisplayGeometry
	InstanceDisplayGeometry is an extension of IRenderGeometry dealing with instancing. More...

Functions
DWORD	ConvertFromR8G8B8ToDWORD (int r, int g, int b)
	This function converts from a color r,g,b in bytes (range 0 to 255) to a combined DWORD used internally by 3ds Max for storing Vertex Colors.

Detailed Description

This API is about having a single INode in the scene, but having many geometries being instantiated at the GPU level in the viewport when the INode is drawn, e.g : a particles system.

MaxSDK::Graphics::InstanceDisplayGeometry is a class dealing with instancing geometries in the viewport (only in the viewport, not at render time). It is a subclass of MaxSDK::Graphics::IRenderGeometry, and in that class you provide a geometry that is used by Nitrous (the 3ds Max modern viewport) to be displayed in the viewport. That geometry is provided at the GPU level by giving vertex buffers and material stream requirement. 3ds Max is implementing all the following functions, you don't need to override any of those to make the API work.

In MaxSDK::Graphics::InstanceDisplayGeometry, you provide the same information for the geometry that you would provide in MaxSDK::Graphics::IRenderGeometry, but you also add some information about instancing that geometry in multiple ways in the viewport, still using the same single INode. It's not related to the instances/references you have for an INode in the user interface. This API was developed for dealing with animated instances in mind, so performance is taken into consideration.

This viewport instancing API has 2 modes : 1) The creation mode, to create the instances using InstanceDisplayGeometry::CreateInstanceData(const InstanceData& data) where you provide the initial data for instancing an object. 2) The update mode, to update the instances using InstanceDisplayGeometry::UpdateInstanceData(const InstanceData& data). It may be used to animate the instances from one frame to another such as update their positions The update mode should be used only if you have at least called InstanceDisplayGeometry::CreateInstanceData(const InstanceData& data) once before so the instance data is created. This mode has a better performance than recreating the whole instance data with InstanceDisplayGeometry::CreateInstanceData(const InstanceData& data) since we are only updating the existing data, no vertex buffers are recreated. There are restrictions to using it, since you can not change the number of instances or provide new data that was not present initially nor change the number of vertices from the instantiated geometry.

Note : When a viewport is in high quality (instead of the standard quality which is the default), the geometry or its instances are only displayed correctly if the following data in the vertex buffers is provided (this is the material stream requirement ): 1) The vertices' positions 2) The vertices' normals 3) A UV map channel (can be any map channel) 4) A UV map channel (can be any map channel also be the same as the map channel from 3) ) 5) A UV map channel (can be any map channel also be the same as the map channel from 3) ) 6) A UV map channel (can be any map channel also be the same as the map channel from 3) ) 7) The tangents for normal mapping 8) The bitangents for normal mapping

Even if you don't use normal mapping or vertex color, you must provide this data in high quality viewports.

Link with optimesh.lib to use this API.

Function Documentation

ConvertFromR8G8B8ToDWORD()

DWORD ConvertFromR8G8B8ToDWORD ( int r, int g, int b )

inline

This function converts from a color r,g,b in bytes (range 0 to 255) to a combined DWORD used internally by 3ds Max for storing Vertex Colors.

{
    DbgAssert((r>=0 && r<=255) && (g>=0 && g<=255) && (b>=0 && b<=255) );
    return ((((WORD)((BYTE)(b)) << 8)) | (((DWORD)(BYTE)(g)) << 16) | (((DWORD)(BYTE)(r)) << 24));
}