3ds Max C++ API Reference
RenderInstance Class Referenceabstract

This class provides information about a single node being rendered. More...

#include <RenderInstance.h>

+ Inheritance diagram for RenderInstance:

Public Member Functions

virtual ~RenderInstance ()
 Destructor. More...
 
void SetFlag (ULONG f, BOOL b)
 Sets the specified flag(s) to the state passed. More...
 
void SetFlag (ULONG f)
 Sets the specified flag(s) to on. More...
 
void ClearFlag (ULONG f)
 Clears the specified flag(s). More...
 
BOOL TestFlag (ULONG f)
 Returns TRUE if the specified flag(s) are set; otherwise FALSE. More...
 
BOOL Hidden ()
 
BOOL IsClip ()
 
virtual RenderInstanceNext ()=0
 Returns a pointer to the next in RenderInstance in the list. More...
 
virtual Interval MeshValidity ()=0
 Returns the validity interval of the mesh of this render instance. More...
 
virtual int NumLights ()=0
 Returns the number of lights affecting the node. More...
 
virtual LightDescLight (int n)=0
 Returns a pointer to the LightDesc for the 'i-th' light affecting the node. More...
 
virtual BOOL CastsShadowsFrom (const ObjLightDesc &lt)=0
 
virtual INodeGetINode ()=0
 Returns the INode pointer for the instance. More...
 
virtual ObjectGetEvalObject ()=0
 Returns a pointer to the evaluated object for the instance. More...
 
virtual ULONG MtlRequirements (int mtlNum, int faceNum)=0
 Returns the material requirements of the material assigned to the node. More...
 
virtual Point3 GetFaceNormal (int faceNum)=0
 Returns the geometric normal of the specified face in object space. More...
 
virtual Point3 GetFaceVertNormal (int faceNum, int vertNum)=0
 Returns the vertex normal of the specified face in camera coordinates. More...
 
virtual void GetFaceVertNormals (int faceNum, Point3 n[3])=0
 Returns the three vertex normals of the specified face in camera coordinates. More...
 
virtual Point3 GetCamVert (int vertnum)=0
 Returns the coordinate for the specified vertex in camera coordinates. More...
 
virtual void GetObjVerts (int fnum, Point3 obp[3])=0
 Returns the vertices of the specified face in object coordinates. More...
 
virtual void GetCamVerts (int fnum, Point3 cp[3])=0
 Returns the vertices of the specified face in camera (view) coordinates. More...
 
virtual INT_PTR Execute (int, ULONG_PTR=0, ULONG_PTR=0, ULONG_PTR=0)
 
virtual MtlGetMtl (int faceNum)=0
 

Public Attributes

ULONG flags
 
Mtlmtl
 
float wireSize
 
Meshmesh
 
float vis
 
int nodeID
 
int objMotBlurFrame
 
int objBlurID
 
Matrix3 objToWorld
 
Matrix3 objToCam
 
Matrix3 normalObjToCam
 
Matrix3 camToObj
 
Box3 obBox
 
Point3 center
 
float radsq
 

Additional Inherited Members

- Static Public Member Functions inherited from MaxHeapOperators
static UtilExport voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e)
 Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new (size_t size, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new (size_t size, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport voidoperator new[] (size_t size, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
 
static UtilExport voidoperator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
 New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
 
static UtilExport void operator delete (void *ptr)
 Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete (void *ptr, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e)
 Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, int block_type, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
 Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
 
static UtilExport void operator delete[] (void *ptr, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport void operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
 Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
 
static UtilExport voidoperator new (size_t size, void *placement_ptr)
 Placement new operator. More...
 
static UtilExport void operator delete (void *ptr, void *placement_ptr)
 Placement delete operator. More...
 
static UtilExport voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary. More...
 
static UtilExport voidaligned_realloc (void *ptr, size_t size, size_t alignment)
 Reallocates memory on a specified alignment boundary. More...
 
static UtilExport void aligned_free (void *ptr)
 Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...
 

Detailed Description

This class provides information about a single node being rendered.

This includes information such as the mesh of the object, its material, unique node ID, object space bounding extents, number of lights affecting it, material requirements, and normals and vertex coordinates in various spaces (object and camera).

Data Members:
ULONG flags;

The flags that describe the properties of this instance. See Render Instance Flags .

Mtl *mtl;

This is the material from the node.

float wireSize;

The wireframe size.

Mesh *mesh;

The mesh to be rendered. This is the result of GeomObject::GetRenderMesh().

float vis;

Object visibility (between 0.0 and 1.0). This is the value the visibility track evaluates to at a particular time.

int nodeID;

A unique ID associated with the node. It's unique within the scene during a render.

int objMotBlurFrame;

This will be equal to NO_MOTBLUR for all non-blurred objects. For blurred objects, it takes on the values (0..nBlurFrames-1) for the successive blur-instances.

int objBlurID;

The purpose of this is to differentiate blur-instances generated from different nodes. All the blur-instances for an object-motion-blurred object will have the same objBlurID. This is as distinct from nodeID, which is different for every instance. This makes it possible to easily avoid intersecting a ray with all blur-instances for an object. If RenderGlobalContext::IntersectWorld() is being used, then passing in the objBlurID for the parameter skipID will have this effect.

The basic technique is this: When reflecting or refracting rays, and object motion blur is enabled, choose sub-frame times randomly for the different rays (effectively giving a coarse stochastic sampling of time).

Matrix3 objToWorld;

This matrix can be used to transform object coordinates to world coordinates.

Matrix3 objToCam;

This matrix can be used to transform object coordinates to camera coordinates.

Matrix3 normalObjToCam;

This matrix can be used for transforming surface normals from object space to camera space.

Matrix3 camToObj;

This matrix can be used to transform camera coordinates to object coordinates.

Box3 obBox;

The object space extents of the object being rendered.

Point3 center;

The object bounding sphere center (in camera coordinates)

float radsq;

The square of the bounding sphere's radius.
See also
Class Mtl, Class LightDesc, Class INode, Class Object, Class Mesh, Class Matrix3, Class Box3, Class Point3, Class Interval.

Constructor & Destructor Documentation

◆ ~RenderInstance()

virtual ~RenderInstance ( )
inlinevirtual

Destructor.

112 {}

Member Function Documentation

◆ SetFlag() [1/2]

void SetFlag ( ULONG  f,
BOOL  b 
)
inline

Sets the specified flag(s) to the state passed.

Parameters:
ULONG f

The flags to set. See Render Instance Flags .

BOOL b

The state to set; TRUE for on; FALSE for off.
120 { if (b) flags |= f; else flags &= ~f; }
ULONG flags
Definition: RenderInstance.h:95

◆ SetFlag() [2/2]

void SetFlag ( ULONG  f)
inline

Sets the specified flag(s) to on.

Parameters:
ULONG f

The flags to set. See Render Instance Flags .
125 { flags |= f; }

◆ ClearFlag()

void ClearFlag ( ULONG  f)
inline

Clears the specified flag(s).

Parameters:
ULONG f

The flags to set to zero. See Render Instance Flags .
130 { flags &= ~f; }

◆ TestFlag()

BOOL TestFlag ( ULONG  f)
inline

Returns TRUE if the specified flag(s) are set; otherwise FALSE.

Parameters:
ULONG f

The flags to set to zero. See Render Instance Flags
136 { return flags&f?1:0; }

◆ Hidden()

BOOL Hidden ( )
inline
137 { return TestFlag(INST_HIDE); }
BOOL TestFlag(ULONG f)
Returns TRUE if the specified flag(s) are set; otherwise FALSE.
Definition: RenderInstance.h:136
#define INST_HIDE
instance is hidden
Definition: RenderInstance.h:27

◆ IsClip()

BOOL IsClip ( )
inline
138 { return TestFlag(INST_CLIP); }
#define INST_CLIP
clip instance: ray tracers should skip it
Definition: RenderInstance.h:28

◆ Next()

virtual RenderInstance* Next ( )
pure virtual

Returns a pointer to the next in RenderInstance in the list.

A pointer to the first element in the list may to retrieved from RenderGlobalContext::InstanceList().

◆ MeshValidity()

virtual Interval MeshValidity ( )
pure virtual

Returns the validity interval of the mesh of this render instance.

◆ NumLights()

virtual int NumLights ( )
pure virtual

Returns the number of lights affecting the node.

◆ Light()

virtual LightDesc* Light ( int  n)
pure virtual

Returns a pointer to the LightDesc for the 'i-th' light affecting the node.

Parameters:
int n

Specifies which light.

◆ CastsShadowsFrom()

virtual BOOL CastsShadowsFrom ( const ObjLightDesc lt)
pure virtual
Remarks
Returns TRUE if this particular instance will cast shadows from the particular light based on the light's Exclusion/Inclusion list; FALSE if it won't cast shadows.
Parameters:
const ObjLightDesc& lt

Describes the light. See Class ObjLightDesc.

◆ GetINode()

virtual INode* GetINode ( )
pure virtual

Returns the INode pointer for the instance.

◆ GetEvalObject()

virtual Object* GetEvalObject ( )
pure virtual

Returns a pointer to the evaluated object for the instance.

You can use this to get more information about the type of object being rendered. For instance you could look at the Class_ID and recognize it as a sphere, a box, a torus, etc.

◆ MtlRequirements()

virtual ULONG MtlRequirements ( int  mtlNum,
int  faceNum 
)
pure virtual

Returns the material requirements of the material assigned to the node.

See Material Requirements Flags.

Parameters:
int mtlNum

Specifies the number of the sub-material whose requirements should be returned. A value of -1 may be passed to return a value generated by looping over all the sub-materials and ORing together the requirements.

int faceNum

This is the integer face number for objects which support material per face (if flag INST_MTL_BYFACE is set). See Class IChkMtlAPI.

◆ GetFaceNormal()

virtual Point3 GetFaceNormal ( int  faceNum)
pure virtual

Returns the geometric normal of the specified face in object space.

Parameters:
int faceNum

Zero based index of the face whose normal is returned.

◆ GetFaceVertNormal()

virtual Point3 GetFaceVertNormal ( int  faceNum,
int  vertNum 
)
pure virtual

Returns the vertex normal of the specified face in camera coordinates.

Parameters:
int faceNum

Zero based index of the face in the mesh.

int vertNum

Zero based index of the vertex in the face.

◆ GetFaceVertNormals()

virtual void GetFaceVertNormals ( int  faceNum,
Point3  n[3] 
)
pure virtual

Returns the three vertex normals of the specified face in camera coordinates.

Parameters:
int faceNum

Zero based index of the face in the mesh.

Point3 n[3]

The normals are returned here.

◆ GetCamVert()

virtual Point3 GetCamVert ( int  vertnum)
pure virtual

Returns the coordinate for the specified vertex in camera coordinates.

Parameters:
int vertnum

The zero based index of the vertex in the mesh.

◆ GetObjVerts()

virtual void GetObjVerts ( int  fnum,
Point3  obp[3] 
)
pure virtual

Returns the vertices of the specified face in object coordinates.

Parameters:
int fnum

Zero based index of the face in the mesh.

Point3 obp[3]

The three vertices of the face in object coordinates.

◆ GetCamVerts()

virtual void GetCamVerts ( int  fnum,
Point3  cp[3] 
)
pure virtual

Returns the vertices of the specified face in camera (view) coordinates.

Parameters:
int fnum

Zero based index of the face in the mesh.

Point3 cp[3]

The three vertices of the face in camera coordinates.

◆ Execute()

virtual INT_PTR Execute ( int  ,
ULONG_PTR  = 0,
ULONG_PTR  = 0,
ULONG_PTR  = 0 
)
inlinevirtual
Remarks
This is a general purpose function that allows the API to be extended in the future. The 3ds Max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.
Parameters:
int cmd

The index of the command to execute.

ULONG_PTR arg1=0

Optional argument 1. See the documentation where the cmd option is discussed for more details on these parameters.

ULONG_PTR arg2=0

Optional argument 2.

ULONG_PTR arg3=0

Optional argument 3.
Returns
An integer return value. See the documentation where the cmd option is discussed for more details on the meaning of this value.
Default Implementation:
{ return 0; }
245 { return 0; }

◆ GetMtl()

virtual Mtl* GetMtl ( int  faceNum)
pure virtual
Remarks
Objects can provide a material as a function of face number via the interface provided by Class IChkMtlAPI. This method will return RenderInstance::mtl if flag INST_MTL_BYFACE is not set. If INST_MTL_BYFACE is set it will return the proper by-face material. See Render Instance Flags .
Parameters:
int faceNum

The zero based index of the face in the mesh.

Objects can provide a material as a function of face number via the IChkMtlAPI interface (chkmtlapi.h).

Member Data Documentation

◆ flags

ULONG flags

◆ mtl

Mtl* mtl

◆ wireSize

float wireSize

◆ mesh

Mesh* mesh

◆ vis

float vis

◆ nodeID

int nodeID

◆ objMotBlurFrame

int objMotBlurFrame

◆ objBlurID

int objBlurID

◆ objToWorld

Matrix3 objToWorld

◆ objToCam

Matrix3 objToCam

◆ normalObjToCam

Matrix3 normalObjToCam

◆ camToObj

Matrix3 camToObj

◆ obBox

Box3 obBox

◆ center

Point3 center

◆ radsq

float radsq