3ds Max C++ API Reference
IVirtualDevice Class Referenceabstract

This class provides low level access to the GPU device. More...

#include <IVirtualDevice.h>

+ Inheritance diagram for IVirtualDevice:

Public Member Functions

virtual unsigned int ThreadID ()=0
 Returns the thread id of the virtual device. More...
 
virtual bool IsValid () const =0
 Gets the status of the device. More...
 
virtual bool BeginFrame ()=0
 Begins a frame draw. More...
 
virtual bool EndFrame ()=0
 Ends a frame draw. More...
 
virtual bool BeginScene ()=0
 Begins a scene draw. More...
 
virtual bool EndScene ()=0
 Ends a scene draw. More...
 
virtual const RasterizerStateGetRasterizerState ()=0
 Gets the current rasterizer state. More...
 
virtual void SetRasterizerState (const RasterizerState &newState)=0
 Sets the current rasterizer state. More...
 
virtual const DepthStencilStateGetDepthStencilState ()=0
 Gets the current depth-stencil state. More...
 
virtual void SetDepthStencilState (const DepthStencilState &newState)=0
 Sets the current depth stencil state. More...
 
virtual const BlendStateGetBlendState ()=0
 Gets the current blend state. More...
 
virtual void SetBlendState (const BlendState &newState)=0
 Sets the current depth stencil state. More...
 
virtual const Box2 Viewport ()=0
 Gets the pixel coordinate viewport for the drawing. More...
 
virtual void Viewport (const Box2 *vp)=0
 Sets the pixel coordinate viewport for the drawing. More...
 
virtual const Point2 DepthRange () const =0
 Gets the depth range. More...
 
virtual void DepthRange (const Point2 &depthRange)=0
 Sets the depth range. More...
 
virtual const Box2 ScissorBox ()=0
 Gets scissor box in pixels. More...
 
virtual void ScissorBox (const Box2 *box)=0
 Sets the scissor box in pixels. More...
 
virtual size_t VertexStreamCount () const =0
 Gets the number of vertex buffer streams. More...
 
virtual VertexBufferHandle GetVertexStream (int nStream) const =0
 Gets the specified vertex buffer stream. More...
 
virtual void SetVertexStreams (VertexBufferHandleArray &bufferArray, int *offsetArray=nullptr)=0
 Sets vertex buffer streams. More...
 
virtual void SetStreamFormat (const MaxSDK::Graphics::MaterialRequiredStreams &format)=0
 
virtual int OutputStreamCount () const =0
 Gets the number of current output vertex buffer streams. More...
 
virtual SmartHandle GetOutputStream (int nStream) const =0
 Gets the specified output vertex buffer stream. More...
 
virtual void SetOutputStreams (SmartHandleArray &bufferArray, int *offsetArray=nullptr)=0
 Sets the current output vertex buffer stream. More...
 
virtual void SetTarget (TargetHandle &target, TargetHandle &zBuffer)=0
 Sets the render target at index 0. More...
 
virtual void SetTargets (TargetHandleArray &targetArray, TargetHandle &zBuffer)=0
 Sets multiple render targets. More...
 
virtual TargetHandle GetTarget (int index)=0
 Gets the specified render target. More...
 
virtual size_t TargetCount ()=0
 Gets the current render target count. More...
 
virtual TargetHandle GetZBuffer ()=0
 Gets the current z buffer. More...
 
virtual IndexBufferHandle GetIndexBuffer () const =0
 Gets the current index buffer. More...
 
virtual void SetIndexBuffer (IndexBufferHandle &indexBuffer)=0
 Sets the current index buffer. More...
 
virtual void Draw (PrimitiveType type, int start, int primCount)=0
 Draws part of a set of primitives. More...
 
virtual void DrawInstanced (PrimitiveType type, int instanceCount, int start, int primCount)=0
 Draws part of a set of primitives with an instance. More...
 
virtual void Clear (BufferClearFlag flags, const AColor &color, float z, int stencil)=0
 Performs a full clear: target( nTargets ) to a given color, z to a given z, stencil to a given stencil. More...
 
virtual void ClearRegion (const Box2 &rect, BufferClearFlag flags, const AColor &color, float z, int stencil)=0
 Performs a partial clear: a sub-region of the target/z/stencil is cleared. More...
 
virtual bool SetTargetsAndUnorderedAccessViews (TargetHandleArray targets, TargetHandle &zBuffer, VertexBufferHandleArray uavs, unsigned int *initialUAVCounts)=0
 Set Render Targets and Unordered Access View targets. More...
 
virtual void ClearUnorderedAccessView (VertexBufferHandle buffer, const unsigned int vals[4])=0
 Clear a Unordered Access View target with initial value. More...
 

Protected Member Functions

virtual ~IVirtualDevice ()
 

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 low level access to the GPU device.

It wraps the variable 3D API into an unified interface. This means you do not need to know whether the real device is actually Direct3D9, Direct3D11 or OpenGL. Similar to the device interface in Direct3D, this interface provides rendering functions such as Draw() and DrawInstanced(), and resource functions like SetVertexStreams(), SetIndexBuffer() and so on. You can also change render states via Get/SetBlendState(), Get/SetRasterizerState(), and Get/SetDepthStencilState(). For example, to change the Z-Bias of the next draw call, use RasterizerState::SetDepthBias() or RasterizerState::SetSlopeScaledDepthBias().

See also
For information about how to obtain the draw context and work with the Nitrous API, see Low-level Device API and About RenderItem. You should read all the topics on Nitrous before developing Nitrous plugins.

For an example of code that implements this interface, see the sample project in howto/Graphiccs/GPUParticle.

Example Code:

Typical usage of rendering geometry data may look like this:

class SampleItemDX9 : public ICustomRenderItem
{
...
};
void SampleItemDX9::Display(DrawContext& dc)
{
IVirtualDevice& vd = drawContext.GetVirtualDevice();
BaseMaterialHandle& material = const_cast<BaseMaterialHandle&>(drawContext.GetMaterial()); //Use draw context’s material
vd.SetStreamFormat(const_cast<MaterialRequiredStreams&>(*material.GetRequiredStreams()));
vd.SetVertexStreams(mVertexBuffer);
vd.SetIndexBuffer(&mIndexBuffer);
material.Activate(drawContext);
unsigned int passCount = material.GetPassCount(drawContext);
for (int pass = 0; pass < passCount; ++pass) //Loop through all passes
{
material.ActivatePass(drawContext, pass);
vd.Draw(PrimitiveTriangleList, 0, (int)mPrimitiveCount);
}
material.Terminate(drawContext);
}
@ PrimitiveTriangleList
A list of unconnected triangles, yielding (vertex_count / 3) triangles.
Definition: RenderEnums.h:41

Typical usage of stream-out data may look like this:

//Turn off Z-Buffer
vd.SetDepthStencilState(mDepthOffState);
streamOutEffect.Activate(drawContext);
streamOutEffect.ActivatePass(drawContext, 0);
vd.SetStreamFormat(streamOutEffect.GetStreamFormat());
vd.SetIndexBuffer(nullptr);
vd.SetVertexStreams(mRawDataBuffers);
vd.SetOutputStreams(&mStreamOutBuffers);
vd.Draw(PrimitivePointList, 0, (int)vertexCount);
vd.SetOutputStreams(nullptr);
streamOutEffect.PassesFinished(drawContext);
streamOutEffect.Terminate();
//Restore Z-Buffer state
vd.SetDepthStencilState(mBackupState);
@ PrimitivePointList
A list of independent points.
Definition: RenderEnums.h:27

Constructor & Destructor Documentation

◆ ~IVirtualDevice()

virtual ~IVirtualDevice ( )
inlineprotectedvirtual
94 {}

Member Function Documentation

◆ ThreadID()

virtual unsigned int ThreadID ( )
pure virtual

Returns the thread id of the virtual device.

Returns
Return 0 for DirectX9, the real thread id for DirectX11.

◆ IsValid()

virtual bool IsValid ( ) const
pure virtual

Gets the status of the device.

Note: When IsValid is false, all device-related resources may be invalid. Sometimes plugins may attempt to dispose after Nitrous has already done so. At this time, any calls to device resources may cause a crash. Therefore, plugins should check this flag to make sure the device is valid before releasing the resources.

Returns
true if the device is valid. false if not.

◆ BeginFrame()

virtual bool BeginFrame ( )
pure virtual

Begins a frame draw.

Should be paired with EndFrame(). Brackets sets of drawing calls, only 1 level deep allowed.

◆ EndFrame()

virtual bool EndFrame ( )
pure virtual

Ends a frame draw.

Should be paired with BeginFrame().

◆ BeginScene()

virtual bool BeginScene ( )
pure virtual

Begins a scene draw.

Brackets sets of drawing calls. Only 1 level deep allowed.

◆ EndScene()

virtual bool EndScene ( )
pure virtual

Ends a scene draw.

◆ GetRasterizerState()

virtual const RasterizerState& GetRasterizerState ( )
pure virtual

Gets the current rasterizer state.

Returns
The rasterizer state handle.

◆ SetRasterizerState()

virtual void SetRasterizerState ( const RasterizerState newState)
pure virtual

Sets the current rasterizer state.

Parameters
[in]newStatethe new rasterizer state.

◆ GetDepthStencilState()

virtual const DepthStencilState& GetDepthStencilState ( )
pure virtual

Gets the current depth-stencil state.

Returns
The depth stencil state handle.

◆ SetDepthStencilState()

virtual void SetDepthStencilState ( const DepthStencilState newState)
pure virtual

Sets the current depth stencil state.

Parameters
[in]newStateThe new depth stencil state handle.

◆ GetBlendState()

virtual const BlendState& GetBlendState ( )
pure virtual

Gets the current blend state.

Returns
The current blend state handle.

◆ SetBlendState()

virtual void SetBlendState ( const BlendState newState)
pure virtual

Sets the current depth stencil state.

Parameters
[in]newStateThe new blend state handle.

◆ Viewport() [1/2]

virtual const Box2 Viewport ( )
pure virtual

Gets the pixel coordinate viewport for the drawing.

Returns
The viewport's {0,0,w,h}, or {0,0,0,0} if no target is defined.

◆ Viewport() [2/2]

virtual void Viewport ( const Box2 vp)
pure virtual

Sets the pixel coordinate viewport for the drawing.

Parameters
[in]vpThe desired viewport size, or nullptr which means "use the full screen".

◆ DepthRange() [1/2]

virtual const Point2 DepthRange ( ) const
pure virtual

Gets the depth range.

Returns
The depth range, normally between 0.0 to 1.0.

◆ DepthRange() [2/2]

virtual void DepthRange ( const Point2 depthRange)
pure virtual

Sets the depth range.

Parameters
[in]depthRangeThe depth range, depthRange.x means near distance, depthRange.y means far distance. Normally the values are in the range 0.0 to 1.0.

◆ ScissorBox() [1/2]

virtual const Box2 ScissorBox ( )
pure virtual

Gets scissor box in pixels.

Returns
The scissor box. The default value is the current render target size.

◆ ScissorBox() [2/2]

virtual void ScissorBox ( const Box2 box)
pure virtual

Sets the scissor box in pixels.

Parameters
[in]boxThe scissor box, nullptr means no scissor clip.

◆ VertexStreamCount()

virtual size_t VertexStreamCount ( ) const
pure virtual

Gets the number of vertex buffer streams.

Returns
The current number of active streams.

◆ GetVertexStream()

virtual VertexBufferHandle GetVertexStream ( int  nStream) const
pure virtual

Gets the specified vertex buffer stream.

Parameters
[in]nStreamThe stream index of the vertex buffer.
Returns
The vertex buffer handle at nStream.

◆ SetVertexStreams()

virtual void SetVertexStreams ( VertexBufferHandleArray bufferArray,
int offsetArray = nullptr 
)
pure virtual

Sets vertex buffer streams.

Parameters
[in]bufferArrayThe vertex buffer array.
[in]offsetArrayoffset of each vertex buffer, must have same size as the buffer

◆ SetStreamFormat()

virtual void SetStreamFormat ( const MaxSDK::Graphics::MaterialRequiredStreams format)
pure virtual

◆ OutputStreamCount()

virtual int OutputStreamCount ( ) const
pure virtual

Gets the number of current output vertex buffer streams.

Returns
The number of current output vertex buffer streams.

◆ GetOutputStream()

virtual SmartHandle GetOutputStream ( int  nStream) const
pure virtual

Gets the specified output vertex buffer stream.

Note: this function only works for DX11 devices.

Parameters
[in]nStreamThe index of the stream.
Returns
The vertex buffer handle at output nStream. For dx9 devices (feature level < LEVEL_4_0), an invalid handle is returned. Use VertexBufferHandle::IsValid() to check the validity.

◆ SetOutputStreams()

virtual void SetOutputStreams ( SmartHandleArray bufferArray,
int offsetArray = nullptr 
)
pure virtual

Sets the current output vertex buffer stream.

Note: The max number of output streams is 0 for DX9 devices, 4 for DX11 devices.

Parameters
[in]bufferArraySets output streams. Use nullptr to clear output streams.
[in]offsetArrayoffset of each vertex buffer, must have same size as the buffer. Specify -1 to append to last stream out position.

◆ SetTarget()

virtual void SetTarget ( TargetHandle target,
TargetHandle zBuffer 
)
pure virtual

Sets the render target at index 0.

Parameters
[in]targetA pointer for the render target handle.
[in]zBufferA pointer for the z buffer handle. The size of zBuffer must be equal to or larger than the target. Can be nullptr.

◆ SetTargets()

virtual void SetTargets ( TargetHandleArray targetArray,
TargetHandle zBuffer 
)
pure virtual

Sets multiple render targets.

Parameters
[in]targetArrayThe render targets to be set. All targets must have the same size.
[in]zBufferA pointer to the z buffer handle. The size of zBuffer must be equal to or larger than the render targets. Can be nullptr.

◆ GetTarget()

virtual TargetHandle GetTarget ( int  index)
pure virtual

Gets the specified render target.

Parameters
[in]indexThe index of the target. For DX9, the maximum number of the index is 4, for DX11, it's 8.
Returns
The target handle. The handle might be invalid if the corresponding index doesn't exist.

◆ TargetCount()

virtual size_t TargetCount ( )
pure virtual

Gets the current render target count.

Returns
The current target count.

◆ GetZBuffer()

virtual TargetHandle GetZBuffer ( )
pure virtual

Gets the current z buffer.

Returns
The current z buffer. The handle might be invalid if the z buffer doesn't exist.

◆ GetIndexBuffer()

virtual IndexBufferHandle GetIndexBuffer ( ) const
pure virtual

Gets the current index buffer.

Returns
The current index buffer handle.

◆ SetIndexBuffer()

virtual void SetIndexBuffer ( IndexBufferHandle indexBuffer)
pure virtual

Sets the current index buffer.

Parameters
[in]indexBufferThe index buffer handle. Pass nullptr to clear the current index buffer.

◆ Draw()

virtual void Draw ( PrimitiveType  type,
int  start,
int  primCount 
)
pure virtual

Draws part of a set of primitives.

Parameters
[in]typeThe primitive type.
[in]startThe start vertex index in the current vertex buffer.
[in]primCountThe number of primitives to draw.

◆ DrawInstanced()

virtual void DrawInstanced ( PrimitiveType  type,
int  instanceCount,
int  start,
int  primCount 
)
pure virtual

Draws part of a set of primitives with an instance.

Note: you need call VertexBufferHandle::SetInstanceCount() to set the instance count of the instance data stream.

Parameters
[in]typeThe primitive type.
[in]instanceCountThe number of instances.
[in]startThe start vertex index in the current vertex buffer.
[in]primCountThe number of primitives to draw.

◆ Clear()

virtual void Clear ( BufferClearFlag  flags,
const AColor color,
float  z,
int  stencil 
)
pure virtual

Performs a full clear: target( nTargets ) to a given color, z to a given z, stencil to a given stencil.

The target (or MRT targets), instead of the viewport, is cleared. The clear operation is not affected by the scissor box.

Parameters
[in]flagsThe components to clear.
[in]colorThe color after the clear. Available when ClearBackbuffer or ClearAll is set.
[in]zThe z value after the clear. Available when ClearDepthBuffer or ClearAll is set.
[in]stencilThe stencil value after clear. Available when ClearStencilBuffer or ClearAll is set.

◆ ClearRegion()

virtual void ClearRegion ( const Box2 rect,
BufferClearFlag  flags,
const AColor color,
float  z,
int  stencil 
)
pure virtual

Performs a partial clear: a sub-region of the target/z/stencil is cleared.

The region is clipped to the bounds of the viewport rectangle, and the clear operation is not affected by the scissor box.

Parameters
[in]rectThe region to clear.
[in]flagsThe components to clear.
[in]colorThe color after the clear. Available when ClearBackbuffer or ClearAll is set.
[in]zThe z value after the clear. Available when ClearDepthBuffer or ClearAll is set.
[in]stencilThe stencil value after the clear. Available when ClearStencilBuffer or ClearAll is set.

◆ SetTargetsAndUnorderedAccessViews()

virtual bool SetTargetsAndUnorderedAccessViews ( TargetHandleArray  targets,
TargetHandle zBuffer,
VertexBufferHandleArray  uavs,
unsigned int initialUAVCounts 
)
pure virtual

Set Render Targets and Unordered Access View targets.

Parameters
[in]targetsrender targets array
[in]zBufferz buffer, can be nullptr
[in]uavsUAV targets
[in]initialUAVCountsInitial count array of the UAV. The array should be same size as uavs.

◆ ClearUnorderedAccessView()

virtual void ClearUnorderedAccessView ( VertexBufferHandle  buffer,
const unsigned int  vals[4] 
)
pure virtual

Clear a Unordered Access View target with initial value.

This API wraps DX11 API, it works on FLOAT, UNORM, and SNORM unordered access views (UAVs), with format conversion from FLOAT to *NORM where appropriate.

Parameters
[in]bufferuav buffer to clear
[in]vals4 unsigned int values to copy to corresponding UAV's RGBA channels.