IPrimitiveRenderer Class Reference
 
 
 
IPrimitiveRenderer Class Reference

This reference page is linked to from the following overview topics: Nitrous Graphics SDK Extensions.


#include <IPrimitiveRenderer.h>

Inheritance diagram for IPrimitiveRenderer:
MaxHeapOperators

Class Description

This class is used to draw simple primitives, markers, text with given material and transformations.

Description
The class provides various ways to draw objects. Many functions are self contained and handle much of the code for you by using SimpleVertexStream, whilst others give you complete control over how the primitive is drawn. For example DrawPrimitive() allows the developer to create vertex and index buffers and define the actual vertex format to be used by providing a StreamFormatHandle which provides formating information for vertex data like Position, UVs and Normals.
Remarks:
This class is running in graphic driver's thread. So sharing data between max thread and driver thread should be designed carefully ensuring thread safety. Users can get an instance of IPrimitiveRenderer in IDisplayCallback::Display().
See also:
IDisplayCallback IVertexBuffer IIndexBuffer

Public Member Functions

virtual const Matrix44 GetWorldMatrix () const =0
  This method gets current row-major world transform matrix.
virtual void  SetWorldMatrix (const Matrix44 &worldMatrix)=0
  This method sets current row-major world transform matrix for example, world matrix with translation should be: | 1 0 0 0 | | 0 1 0 0 | | 0 0 1 0 | | x y z 1 |.
virtual const Matrix44 GetViewMatrix () const =0
  This method gets current row-major view transform matrix.
virtual void  SetViewMatrix (const Matrix44 &viewMatrix)=0
  This method sets current row-major view transform matrix pseudo view matrix should like this: zaxis = normal(At - Eye) xaxis = normal(cross(Up, zaxis)) yaxis = cross(zaxis, xaxis)
virtual const Matrix44 GetProjectionMatrix () const =0
  This method gets current row-major projection transform matrix.
virtual void  SetProjectionMatrix (const Matrix44 &projMatrix)=0
  This method sets current row-major projection transform matrix typical perspective project matrix should like this: | 2*zNear/width 0 0 0 | | 0 2*zNear/height 0 0 | | 0 0 zFar/(zFar-zNear) 1 | | 0 0 zNear*zFar/(zNear-zFar) 0 |.
virtual Rect  GetViewportRect ()=0
  This method gets current viewport rectangle.
virtual Point2  GetDepthRange ()=0
  This method gets current depth range.
virtual void  SetScreenSpace (const Rect &r, const Point2 &depth)=0
  This method sets current viewport rectangle and depth range.
virtual void  Clear (const BufferClearFlag flags, const AColor &color, const float z, const int stencil)=0
  This method clears screen.
virtual void  Clear (const IPoint2 &upperleft, const IPoint2 &bottomright, const BufferClearFlag flags, const AColor &color, const float z, const int stencil)=0
  This method clears sub-region of screen.
virtual void  DrawIndexedPrimitiveUP (PrimitiveType primitiveType, const SimpleVertexStream &vertices, int primitiveCount, const int *indices, int indexCount)=0
  This method draws indexed primitives to screen.
virtual void  DrawPrimitiveUP (PrimitiveType primitiveType, const SimpleVertexStream &vertices, int primitiveCount)=0
  This method draws primitives to screen.
virtual void  DrawPrimitive (MaxSDK::Graphics::PrimitiveType primitiveType, int vertexStart, int primitiveCount)=0
  This method draws primitives based on the current vertex and index buffers.
virtual void  DrawPrimitiveInstanced (MaxSDK::Graphics::PrimitiveType primitiveType, int vertexStart, int primitiveCount, int instanceCount)=0
  This method draws multiple primitives instance from vertex buffer and index buffer.
virtual void  DrawRenderItem (const DisplayCallbackContext &displayContext, const RenderItemHandle &hRenderItem)=0
  Draw a given render item.
virtual void  DrawScreenQuad (float z=0.0f)=0
  This method draws a quad covering the entire current target set.
virtual void  DrawText (const Point3 &xyz, const MCHAR *s)=0
  This method draws a string at given world position.
virtual void  DrawText (const IPoint2 &xy, const MCHAR *s)=0
  This method draws a string at given screen position (upper left is the origin)
virtual bool  BeginMarker ()=0
  This method should be called before AddMarkers.
virtual bool  AddMarkers (MarkerType type, const Point3 *xyz, size_t count, const Color &color=DefaultMarkerColor)=0
  This allows drawing batches of markers at a time.
virtual bool  AddScreenSpaceMarkers (MarkerType type, const Point3 *xyz, size_t count, const Color &color=DefaultMarkerColor)=0
  This allows drawing batches of screen-space markers at a time.
virtual void  EndMarker ()=0
  Ends the marker drawing sequence.
virtual bool  SetMaterial (const BaseMaterialHandle &material)=0
  This method sets current material used by DrawPrimitive and DrawIndexedPrimitive.
virtual BaseMaterialHandle GetMaterial ()=0
  This method gets current material.
virtual void  SetVertexBuffer (size_t count, const VertexBufferHandle *pBuffers)=0
  This method sets vertex buffers used by DrawPrimitive.
virtual void  SetIndexBuffer (const IndexBufferHandle &pIndexBuffer)=0
  This method sets index buffer used by DrawPrimitive.
virtual void  SetStreamFormat (const StreamFormatHandle &format)=0
  This method sets vertex format of vertex buffer.
virtual IRenderStateManager GetRenderStates ()=0
  This method retrieves current render states object.

Static Public Attributes

static GraphicsDriverAPI Color  DefaultMarkerColor

Protected Member Functions

virtual  ~IPrimitiveRenderer ()

Constructor & Destructor Documentation

virtual ~IPrimitiveRenderer ( ) [inline, protected, virtual]
{}

Member Function Documentation

virtual const Matrix44& GetWorldMatrix ( ) const [pure virtual]

This method gets current row-major world transform matrix.

Returns:
current world transform matrix
virtual void SetWorldMatrix ( const Matrix44 worldMatrix ) [pure virtual]

This method sets current row-major world transform matrix for example, world matrix with translation should be: | 1 0 0 0 | | 0 1 0 0 | | 0 0 1 0 | | x y z 1 |.

Parameters:
[in] worldMatrix the new world transform matrix
virtual const Matrix44& GetViewMatrix ( ) const [pure virtual]

This method gets current row-major view transform matrix.

Returns:
current view transform matrix
virtual void SetViewMatrix ( const Matrix44 viewMatrix ) [pure virtual]

This method sets current row-major view transform matrix pseudo view matrix should like this: zaxis = normal(At - Eye) xaxis = normal(cross(Up, zaxis)) yaxis = cross(zaxis, xaxis)

| xaxis.x yaxis.x zaxis.x 0 | | xaxis.y yaxis.y zaxis.y 0 | | xaxis.z yaxis.z zaxis.z 0 | | -dot(xaxis, eye) -dot(yaxis, eye) -dot(zaxis, eye) 1 |

Parameters:
[in] viewMatrix the new view transform matrix
virtual const Matrix44& GetProjectionMatrix ( ) const [pure virtual]

This method gets current row-major projection transform matrix.

Returns:
current 4x4 projection matrix
virtual void SetProjectionMatrix ( const Matrix44 projMatrix ) [pure virtual]

This method sets current row-major projection transform matrix typical perspective project matrix should like this: | 2*zNear/width 0 0 0 | | 0 2*zNear/height 0 0 | | 0 0 zFar/(zFar-zNear) 1 | | 0 0 zNear*zFar/(zNear-zFar) 0 |.

Parameters:
[in] projMatrix projection matrix.
virtual Rect GetViewportRect ( ) [pure virtual]

This method gets current viewport rectangle.

Returns:
current viewport
virtual Point2 GetDepthRange ( ) [pure virtual]

This method gets current depth range.

Returns:
current depth range
virtual void SetScreenSpace ( const Rect r,
const Point2 depth 
) [pure virtual]

This method sets current viewport rectangle and depth range.

Parameters:
[in] viewport area
[in] viewport depth range, x is near plane(default 0), y is far plane(default 1)
virtual void Clear ( const BufferClearFlag  flags,
const AColor color,
const float  z,
const int  stencil 
) [pure virtual]

This method clears screen.

Parameters:
[in] flags the element to clear (Target | Stencil | ZBuffer)
[in] color the Target's clear color
[in] z the value of depth buffer after clear
[in] stencil the stencil value after clear
virtual void Clear ( const IPoint2 upperleft,
const IPoint2 bottomright,
const BufferClearFlag  flags,
const AColor color,
const float  z,
const int  stencil 
) [pure virtual]

This method clears sub-region of screen.

Parameters:
[in] upperleft upper left of clear rect
[in] range the range of clear rect
[in] flags the element to clear (Target | Stencil | ZBuffer)
[in] color the Target's clear color
[in] z the value of depth buffer after clear
[in] stencil the stencil value after clear
virtual void DrawIndexedPrimitiveUP ( PrimitiveType  primitiveType,
const SimpleVertexStream vertices,
int  primitiveCount,
const int *  indices,
int  indexCount 
) [pure virtual]

This method draws indexed primitives to screen.

Parameters:
[in] primitiveType type of primitive (line, triangle)
[in] vertices the primitive data pointer. In system memory.
[in] primitiveCount the number of primitives.
[in] indices the vertices index array A index array stores a lot of integers. Which indicates how the primitive been constructed. For example, a triangle list index "0, 2, 5" means vertex v0, v2 and v5 consist one triangle. A line strip index "0, 3, 1" means vertex v0, v3, v1 consist two lines: one is v0-v3, the other is v3-v1.
[in] indexCount size of the index buffer
virtual void DrawPrimitiveUP ( PrimitiveType  primitiveType,
const SimpleVertexStream vertices,
int  primitiveCount 
) [pure virtual]

This method draws primitives to screen.

Parameters:
[in] primitiveType type of primitive (point, line, triangle)
[in] vertices the primitive data pointer. In system memory.
[in] primitiveCount the number of primitives.
virtual void DrawPrimitive ( MaxSDK::Graphics::PrimitiveType  primitiveType,
int  vertexStart,
int  primitiveCount 
) [pure virtual]

This method draws primitives based on the current vertex and index buffers.

See also:
SetVertexBuffer SetIndexBuffer SetStreamFormat
Parameters:
[in] primitiveType type of primitive (point, line, triangle)
[in] vertexStart the 1st primitives vertex position in vertex buffer
[in] primitiveCount the number of primitives.
virtual void DrawPrimitiveInstanced ( MaxSDK::Graphics::PrimitiveType  primitiveType,
int  vertexStart,
int  primitiveCount,
int  instanceCount 
) [pure virtual]

This method draws multiple primitives instance from vertex buffer and index buffer.

The instance data should be saved in one of the vertex streams. For example, the layout of transform instance stream should be:

                first instance: float4, float4, float4, float4 //Four rows of transform matrix
                second instance: float4, float4, float4, float4 //Four rows of transform matrix
                etc.

When drawing the primitives, each instance's matrix will apply to the primitive. So you can draw multiple instances in one call.

See also:
SetVertexBuffer SetIndexBuffer SetStreamFormat
Parameters:
[in] primitiveType type of primitive (point, line, triangle)
[in] vertexStart the 1st primitives vertex position in vertex buffer
[in] primitiveCount the number of primitives.
[in] instanceCount the number of instances in the stream
virtual void DrawRenderItem ( const DisplayCallbackContext displayContext,
const RenderItemHandle hRenderItem 
) [pure virtual]

Draw a given render item.

Parameters:
[in] displayContext the current display context.
[in] hRenderItem the render item to be draw.
virtual void DrawScreenQuad ( float  z = 0.0f ) [pure virtual]

This method draws a quad covering the entire current target set.

Parameters:
[in] z z value of this quad
virtual void DrawText ( const Point3 xyz,
const MCHAR *  s 
) [pure virtual]

This method draws a string at given world position.

Parameters:
[in] xyz world position of the string
[in] s the text
virtual void DrawText ( const IPoint2 xy,
const MCHAR *  s 
) [pure virtual]

This method draws a string at given screen position (upper left is the origin)

Parameters:
[in] xy screen position of the string
[in] s the text
virtual bool BeginMarker ( ) [pure virtual]

This method should be called before AddMarkers.

It can be used to draw markers. The system will create the appropriate buffer which will be filled up with calls to AddMarker

Returns:
True if successful.
virtual bool AddMarkers ( MarkerType  type,
const Point3 xyz,
size_t  count,
const Color color = DefaultMarkerColor 
) [pure virtual]

This allows drawing batches of markers at a time.

Remarks:
Only call this function between BeginMarker and EndMarker pair
Parameters:
[in] type Marker type
[in] xyz Pointer to a Point3 buffer which contains marker's position in world space
[in] count Number of markers
[in] color Marker's color
Returns:
True if successful. If false, then the buffer has potentially overflowed. Try using EndMarker and start another sequence
virtual bool AddScreenSpaceMarkers ( MarkerType  type,
const Point3 xyz,
size_t  count,
const Color color = DefaultMarkerColor 
) [pure virtual]

This allows drawing batches of screen-space markers at a time.

needed to be drawn.

Remarks:
Only call this function between BeginMarker and EndMarker pair
Parameters:
[in] type Marker type
[in] xyz Pointer to a Point3 buffer which contains marker's position in screen space. z value's range is [0, 1]. "0" is front most and "1" is back most. It is used for comparing depth with other geometries.
[in] count Number of markers
[in] color Marker's color
Returns:
True if successful. If false, then the buffer has potentially overflowed. Try using EndMarker and start another sequence
virtual void EndMarker ( ) [pure virtual]

Ends the marker drawing sequence.

This will draw and flush the internal buffers.

virtual bool SetMaterial ( const BaseMaterialHandle material ) [pure virtual]

This method sets current material used by DrawPrimitive and DrawIndexedPrimitive.

Parameters:
material the new materials' pointer
virtual BaseMaterialHandle& GetMaterial ( ) [pure virtual]

This method gets current material.

Returns:
current material handle
virtual void SetVertexBuffer ( size_t  count,
const VertexBufferHandle pBuffers 
) [pure virtual]

This method sets vertex buffers used by DrawPrimitive.

Remarks:
The number of steams is set by the StreamFormatHandle
Parameters:
count number of vertex buffers, range is 0 to max number of streams - 1
pBuffers vertex buffer array
virtual void SetIndexBuffer ( const IndexBufferHandle pIndexBuffer ) [pure virtual]

This method sets index buffer used by DrawPrimitive.

Parameters:
pIndexBuffer A pointer to the index buffer object
virtual void SetStreamFormat ( const StreamFormatHandle &  format ) [pure virtual]

This method sets vertex format of vertex buffer.

You can set multiple streams with different usage. Instance data must be a separate stream.

Parameters:
pFormat format of vertex buffer
virtual IRenderStateManager& GetRenderStates ( ) [pure virtual]

This method retrieves current render states object.

IRenderStateManager allows the developer to set various graphics states, whilst performing state management.

Returns:
A reference of IRenderStateManager object

Member Data Documentation