Class GraphicsWindow

3DS Max Plug-In SDK

previous page next page

class GraphicsWindow : public InterfaceServer

Description:

The abstract graphics window class. The methods here provide low-level access to 3ds max's graphics system. These methods are available for plug-ins to do any graphics work not possible using the standard high-level graphics methods of 3ds max.

These methods are for use in the existing 3ds max viewports. Note that these APIs are not for casual use, as they are not intended to be a high level graphics library. For example, many steps are required to display a single lit polygon. These APIs are optimized for speed, and not at all for plug-in programmer ease of use.

These methods are provided, however, so that developers can do things that are otherwise impossible using the high-level methods.

Developers should use these methods with an understanding of exactly what they are doing since it's quite easy to crash 3ds max when inappropriate arguments are supplied. The calls are specifically optimized for exactly the way 3ds max uses them. In no way should the calls in GraphicsWindow be considered an "ordinary" 2D/3D API. (That's what OpenGL, D3D, and HEIDI are for.)

One final note of warning: most graphics windows methods execute in a separate thread (or in multiple separate threads) that are owned by the graphics window. Thus, due to thread scheduling, when a bad argument or incorrect sequencing of graphics windows calls causes 3ds max to crash, it is not at all easy to figure out where the problem is. In particular, the location of the main 3ds max thread is not relevant.

All the methods of this class are implemented by the system.

Method Groups:

The hyperlinks below jump to the start of related methods within the class:

Driver/Configuration/Support Methods

Window / Viewport Transformations Methods

Drawing Setup

Drawing Methods (text, polylines, markers)

Device Independent Bitmap Access

Position/Size/Depth/Clipping Methods

Get/Set Buffers Methods

Texture Methods

Material Methods

Lights and Camera Methods

Coordinate Transformation Methods

Hit Testing Methods

Utility Functions

Methods:

Driver/Configuration/Support Methods

Prototype:

virtual void postCreate(int ct, GraphicsWindow **gw)=0;

Remarks:

This method is available in release 2.0 and later only.

This is called after all four GraphicsWindows used by 3ds max are created. SDK users shouldn't need this call

Prototype:

virtual void shutdown()=0;

Remarks:

This method is available in release 2.0 and later only.

This is used to tell the driver that it is shutting down.

Prototype:

virtual int getVersion()=0;

Remarks:

This method is available in release 2.0 and later only.

This returns "0x200" to indicate R2.0

Prototype:

virtual TCHAR *getDriverString()=0;

Remarks:

This method is available in release 2.0 and later only.

This identifies the driver (and includes manufacturer info if available)

Prototype:

virtual void config(HWND hWnd)=0;

Remarks:

This method is available in release 2.0 and later only.

This is called to put up the config dialog if the driver supports GW_SPT_CAN_CONFIG

Parameters:

HWND hWnd

The parent window handle for the dialog.

Prototype:

virtual int querySupport(int what) = 0;

Remarks:

Determines if the driver supports the specified feature.

Parameters:

int what

One of the following values:

GW_SPT_TXT_CORRECT

This is used to enable or gray-out the perspective correction right-click viewport menu option.

GW_SPT_GEOM_ACCEL

This is used to indicate to 3ds max (and the mesh class in particular) that the driver wants to handle all of the 3D data natively. In this case, meshes are rendered by passing 3D world space data and letting the driver transform, clip, and light the vertices. If this returns FALSE, then the mesh class handles all xforms/clip/lighting calculations (using a lazy evaluation algorithm) and then calls the hPolygon or hPolyline 2 1/2D calls for the driver to rasterize. (Primitives that are actually clipped are still sent to the polygon/polyline methods.)

Right now, only the OpenGL driver returns TRUE to this query, but other drivers have been developed that return TRUE, and the HEIDI and D3D drivers may change in the future.

GW_SPT_TRI_STRIPS

If this returns TRUE, then 3ds max will try to stripify meshes before calling the rendering methods. Right now, the drivers just return the user preference that is set in the driver config dialog. It defaults to TRUE.

GW_SPT_DUAL_PLANES

If a driver has dual-planes support it returns TRUE. Our OpenGL display driver only returns TRUE for this if the underlying display driver has implemented a custom OpenGL extension that allows us to handle this efficiently.

GW_SPT_SWAP_MODEL

This returns TRUE if 3ds max has to redraw the whole scene any time the viewports are exposed.

GW_SPT_INCR_UPDATE

This returns TRUE if the driver can update a rectangular subset of the viewport without trashing the image outside that rectangle. This is TRUE for most drivers that blit the viewport region and FALSE for those that do page-flipping in the hardware. For OpenGL, this is TRUE if the display driver implements the Microsoft glSwapRectHintWIN extension.

GW_SPT_1_PASS_DECAL

This is TRUE if the driver can handle decalling with only one pass. Right now, this is TRUE for OpenGL, but FALSE for HEIDI and D3D. (And as with all of these options, it may change in a given driver anytime in the future.)

GW_SPT_DRIVER_CONFIG

This is TRUE if the driver has a configuration dialog box. This is TRUE for all three of our standard drivers.

GW_SPT_TEXTURED_BKG

This is TRUE if the viewport background is implemented as a textured rectangle, and FALSE if it is a blitted bitmap.

GW_SPT_VIRTUAL_VPTS

This is TRUE if the driver allows viewports to be made larger than the physical window they are attached to. Right now this is ony TRUE for OGL.

GW_SPT_PAINT_DOES_BLIT

This is TRUE if WM_PAINT messages result in a blit of the backbuffer (as opposed to a page-flipping swap). This allows 3ds max to do quick damage region repair, and works together with the GW_SPT_SWAP_MODEL flag.

GW_SPT_WIREFRAME_STRIPS

This is TRUE if the driver wants 3ds max to send down wireframe models using triangle strips instead of a bundle of 2-pt segments. This is only used by the OGL driver, and it is there as a user-choosable performance-accuracy tradeoff (since the strips are faster and are back-culled, but they displayhidden edges as though they are visible).

Window / Viewport / Transformations Methods

Prototype:

virtual HWND getHWnd(void)=0;

Remarks:

This method is available in release 2.0 and later only.

This returns the "output" window handle. (Input goes to an invisible window above the viewport. The invisible window is owned by MAX.)

Prototype:

virtual int isPerspectiveView() = 0;

Remarks:

Returns TRUE if the view is in perspective projection; otherwise FALSE (orthographic projection).

Prototype:

virtual void getTextExtents(TCHAR *text, SIZE *sp)=0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the size (in pixels) that the specified text string will occupy

Parameters:

TCHAR *text

The string to check.

SIZE *sp

The size is returned here. See Data Types.

Prototype:

virtual void setTransform(const Matrix3 &m) = 0;

Remarks:

Sets the current transformation matrix, and updates the modeling coordinates to normalized projection coordinates matrix. This routine also back-transforms each light and the eye point (so that lighting can be done in modeling coordinates).

This method may be used to set a matrix that transforms the point passed to the drawing methods (like text(), marker(), polyline() or polygon()). Normally these methods expect world coordinates. However if this matrix is set to an objects transformation matrix you can pass objects space coordinates and they will be transformed into world space (and then put into screen space when they are drawn). If however this is set to the identity matrix you would pass world space coordinates. You can set this matrix to the objects matrix using the following code:

gw->setTransform(inode->GetObjectTM(t));

Note: For world-to-screen space conversions by the methods text(), marker(), polyline(), polygon(), etc, a developer must explicitly set this matrix to the identity. This is because the GraphicsWindow transform may have a non-identity matrix already in place from a previous operation.

Parameters:

const Matrix3 &m

The new current transformation matrix.

Prototype:

virtual BOOL getFlipped()=0;

Remarks:

This is used internally. It returns if the determinant of the current transform is positive or negative. If it's positive 0 is returned; if it's negative 1 is returned.

Prototype:

virtual void setVirtualViewportParams(float zoom, float xOffset, float yOffset) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used to setup a virtual viewport. Note that this is a no-op unless GW_SPT_VIRTUAL_VPTS is TRUE. Plug-in developers should not call this method -- it's for internal use only.

Prototype:

virtual void setUseVirtualViewport(int onOff) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used to set a virtual viewport as active. Note that this is a no-op unless GW_SPT_VIRTUAL_VPTS is TRUE. Plug-in developers should not call this method -- it's for internal use only.

Parameters:

int onOff

TRUE to set the virtual viewport active; FALSE to make it inactive.

Position / Size / Depth / Clipping Methods

Prototype:

virtual void setPos(int x, int y, int w, int h) = 0;

Remarks:

Sets the size and position of the GraphicsWindow. The coordinates are all Windows coordinates in the space of the GraphicsWindows' parent window. (The origin is the upper left.)

Parameters:

int x

Window x origin.

int y

Window y origin.

int w

Window width.

int h

Window height.

Prototype:

virtual void setDisplayState(int s) = 0;

Remarks:

This method is available in release 2.0 and later only.

The specified value may be sent to the driver to indicate the display state of the viewport window controlled by the driver.

Parameters:

int s

The display state to set. One of the following values:

GW_DISPLAY_MAXIMIZED

GW_DISPLAY_WINDOWED

GW_DISPLAY_INVISIBLE

Prototype:

virtual int getDisplayState()=0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the current state. One of the following values:

GW_DISPLAY_MAXIMIZED

GW_DISPLAY_WINDOWED

GW_DISPLAY_INVISIBLE

Prototype:

virtual int getWinSizeX()=0;

Remarks:

This method is available in release 2.0 and later only.

This method gets the current window size in X.

Prototype:

virtual int getWinSizeY()=0;

Remarks:

This method is available in release 2.0 and later only.

This method gets the current window size in Y.

Prototype:

virtual DWORD getWinDepth(void)=0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the z-buffer depth (in bits)

Prototype:

virtual DWORD getHitherCoord()=0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the largest device Z value.

Prototype:

virtual DWORD getYonCoord()=0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the smallest device Z value.

Buffer access methods:

Prototype:

virtual BOOL setBufAccess(int which, int b) = 0;

Remarks:

This method is used internally. Most drivers control two image buffers. One is displayed on the screen, and the other is used to rasterize geometric primitives. When rasterization of a complete frame is done, the off-screen buffer is blitted onto the display screen. This is referred to as dual-plane mode. This method will turn dual-plane mode on or off. This is used internally by the File/Preferences... Viewport page Use Dual Planes toggle.

Parameters:

int which

Specifies which buffer should use dual-planes.

BUF_F_BUFFER

The image (Framebuffer) buffer.

BUF_Z_BUFFER

The Z buffer.

int b

Nonzero to enable access (toggle on); 0 to toggle off.

Return Value:

TRUE if the graphics window has access to the specified buffer; otherwise FALSE.

Prototype:

virtual BOOL getBufAccess(int which) = 0;

Remarks:

This method is used internally. It returns a boolean value indicating if dual plane mode is on or off for the specified buffer.

Parameters:

The buffer whose dual-planes setting will be returned.

int which

The buffer whose dual-planes setting will be returned. One of the following values:

BUF_F_BUFFER

The Framebuffer.

BUF_Z_BUFFER

The Z buffer.

Return Value:

TRUE if the dual-plane mode is on; otherwise FALSE.

Prototype:

virtual BOOL getBufSize(int which, int *size) = 0;

Remarks:

This method is used internally. It retrieves the size of the specified buffer in bytes.

Parameters:

int which

One of the following values:

int *size

The size of the buffer in bytes.

Note the following concerning the HEIDI driver. For HEIDI getBufSize() always returns 10 if dual-planes are on (and 0 otherwise). This is because HEIDI actually never returns the image - it keeps its own copy stored away. Thus the "logical" way to think is that we actually get a copy of the buffer by calling getBuf, and that we give it back by calling setBuf. But in reality (with the HEIDI driver) getBuf and setBuf only tell HEIDI to do some internal buffer manipulation.

Return Value:

TRUE if the size was returned; otherwise FALSE.

Prototype:

virtual BOOL getBuf(int which, int size, void *buf) = 0;

Remarks:

This method is used internally. It retrieves the specified buffer.

Parameters:

int which

The buffer to retrieve. One of the following values:

BUF_F_BUFFER - The image Framebuffer.

BUF_Z_BUFFER - The Z buffer.

int size

The number of bytes to retrieve. This must be at least the size returned from getBufSize().

void *buf

Storage for the buffer data.

Return Value:

TRUE if the buffer was retrieved; otherwise FALSE.

Prototype:

virtual BOOL setBuf(int which, int size, void *buf, RECT *rp) = 0;

Remarks:

Stores the specified buffer.

Parameters:

int which

The buffer to store. One of the following values:

BUF_F_BUFFER - The image Framebuffer.

BUF_Z_BUFFER - The Z buffer.

int size

The number of bytes to store.

void *buf

The buffer data.

RECT *rp

This allows only a subset of the saved image rect to be blitted back to the screen.

Return Value:

TRUE if the buffer was stored; otherwise FALSE.

DIB Methods

Prototype:

virtual BOOL getDIB(BITMAPINFO *bmi, int *size) = 0;

Remarks:

This method returns the viewport image of this graphics window in a packed DIB format. A packed DIB is the standard BMI header followed immediately by all the data bytes (pixels) that make up the image. This is the standard way in Windows to pass a DIB around. See the sample code below for an example of this call in use. Note how it is called twice: once to get the size, once to get the DIB.

Parameters:

BITMAPINFO *bmi

The BITMAPINFO structure defines the dimensions and color information for a Windows device-independent bitmap (DIB). Note that if this parameter is NULL, then only the size value is returned.

int *size

The size of the image in bytes.

Return Value:

TRUE if the image was returned; otherwise FALSE.

Sample Code:

The following sample code saves the current 3ds max viewport to a user specified file.

void TestGetDIB(IObjParam *ip)

{

BITMAPINFO *bmi = NULL;

BITMAPINFOHEADER *bmih;

BitmapInfo biFile;

Bitmap *map;

int size;

TheManager->SelectFileOutput(&biFile,

ip->GetMAXHWnd(), _T("Testing"));

if(!biFile.Name()[0])

return;

ViewExp *vpt = ip->GetActiveViewport();

vpt->getGW()->getDIB(NULL, &size);

bmi = (BITMAPINFO *)malloc(size);

bmih = (BITMAPINFOHEADER *)bmi;

vpt->getGW()->getDIB(bmi, &size);

biFile.SetWidth((WORD)bmih->biWidth);

biFile.SetHeight((WORD)bmih->biHeight);

biFile.SetType(BMM_TRUE_32);

map = TheManager->Create(&biFile);

map->OpenOutput(&biFile);

map->FromDib(bmi);

map->Write(&biFile);

map->Close(&biFile);

if(bmi)

free(bmi);

ip->ReleaseViewport(vpt);

}

Prototype:

virtual BOOL setBackgroundDIB(int width, int height, BITMAPINFO *bmi)=0;

Remarks:

This method is available in release 2.0 and later only.

This method is used internally to zoom the viewport.

Prototype:

virtual void setBackgroundOffset(int x, int y) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used internally to pan the viewport.

Texture Methods

Prototype:

virtual int getTextureSize(int bkg=FALSE) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method returns the size of the texture bitmap that the driver wants sent in to the getTextureHandle() call (if bkg is FALSE). If bkg is TRUE, this returns the size of the texture that 3ds max shoud send to the setBackgroundDIB() call. In general, the return value needs to be a power of 2, though that could be driver-specific

Parameters:

int bkg=FALSE

TRUE to get the size for setBackgroundDIB(); FALSE to get the size for getTextureHandle().

Prototype:

virtual DWORD getTextureHandle(BITMAPINFO *bmi) = 0;

Remarks:

This method returns a handle for the specified texture bitmap. This handle is then used with the setTextureByHandle() method (there is only one current texture active at any time). The texture dimensions must be a power of 2.

When a material is on an object, and the material has a texture map, and when the button used to display the texture map is pressed, 3ds max calls this method to get the texture handle. This basically loads the texture into the hardware RAM (if available). When this mapped object gets displayed the method setTextureHanel() is called. When the material is deleted, or the dispaly in viewport button is turned off, freeTextureHandle() is called.

Parameters:

BITMAPINFO *bmi

The DIB image to use as a texture.

Return Value:

The texture handle.

Prototype:

virtual BOOL setTextureByHandle(DWORD handle) = 0;

Remarks:

This sets the current texture to the image whose handle is passed (see getTextureHandle()). The texture dimensions must be a power of 2.

Parameters:

DWORD handle

The handle of the texture to make current.

Prototype:

virtual void freeTextureHandle(DWORD handle) = 0;

Remarks:

When you are finished with the texture handle, call this method to free it.

Parameters:

DWORD handle

The texture handle to free.

Return Value:

TRUE if the texture was set; otherwise FALSE.

Prototype:

virtual BOOL setTextureTiling(int u, int v, int w=GW_TEX_NO_TILING) = 0;

Remarks:

Sets the way in which textures are tiled across the surface of the object.

Parameters:

The following parameters may use one of these values:

GW_TEX_NO_TILING

The texture clamped - Any UVW that is bigger than 1 is interpreted as being 1.

GW_TEX_REPEAT

As the UVW numbers keep getting larger than 1 the image is repeated.

GW_TEX_MIRROR

If UVW goes beyond 1, the numbers are interpreted as going backwards. So if you had 0 to 2 it would actually go 0 to 1 then 1 down to 0.

int u

The type of texturing in the U direction.

int v

The type of texturing in the V direction.

int w=GW_TEX_NO_TILING

The type of texturing in the W direction.

Return Value:

TRUE if the tiling mode was set; otherwise FALSE.

Prototype:

virtual int getTextureTiling(int which) = 0;

Remarks:

Returns the type of texture tiling set for the particular direction.

For example, if setTextureTiling(GW_TEX_NO_TILING, GW_TEX_REPEAT, GW_TEX_MIRROR) were called first, then

getTextureTiling(0) would yield GW_TEX_NO_TILING, and

getTextureTiling(1) would yield GW_TEX_REPEAT.

Parameters:

int which

This value is 0 or 1 and it represents the U or V direction respectively. The value 2 is not yet implemented.

Return Value:

GW_TEX_NO_TILING

The texture clamped - Any UVW that is bigger than 1 is interpreted as being 1.

GW_TEX_REPEAT

As the UVW numbers keep getting larger than 1 the image is repeated.

GW_TEX_MIRROR

If UVW goes beyond 1, the numbers are interpreted as going backwards. So if you had 0 to 2 it would actually go 0 to 1 then 1 down to 0.

Prototype:

virtual void setTexTransform(const Matrix3 &m) = 0;

Remarks:

This method allows one to put an affine transformation on a texture. This allows you to translate, rotate or scale a texture on an object.

Parameters:

const Matrix3 &m

The texture transformation matrix.

Prototype:

virtual void beginFrame() = 0;

Remarks:

If a developer is working with an existing 3ds max instance of GraphicsWindow (one of MAX's viewports) this method should NOT be called.

Prototype:

virtual void endFrame() = 0;

Remarks:

As above, if a developer is working with an existing 3ds max instance of GraphicsWindow (one of MAX's viewports) this method should NOT be called.

Prototype:

virtual void setViewport(int x, int y, int w, int h) = 0;

Remarks:

This method sets the clipping boundaries within a viewport within the graphics window. This allows more than one viewport to appear within a single graphics window. It has the side-effect of building a 4x4 viewport matrix. This routine should be called anytime the graphics window is resized, or else rendering will still occur to the old window size. (And since most drivers do not do range-checking since it is too time-costly, this could cause a system crash.)

Parameters:

Note: all coordinates are in Windows format, with the origin in the upper left

int x

Specifies the left viewport origin.

int y

Specifies the top viewport origin.

int w

Specifies the viewport width.

int h

Specifies the viewport height.

Drawing Setup

Prototype:

virtual void resetUpdateRect() = 0;

Remarks:

This method resets the update rectangle. The update rectangle is the region of the screen that needs to be updated to reflect items that have changed. When the system is done rendering items, the goal is to only update the region that has actually been altered. This method sets the update rectangle (the region that will be blitted to the display) to invalid. In this way when enlargeUpdateRect() is later called, the RECT passed will be used as the region.

Prototype:

virtual void enlargeUpdateRect(RECT *rp) = 0;

Remarks:

This method enlarges the update rectangle to include the RECT passed. If rp is NULL, then the whole window will later be updated.

Parameters:

RECT *rp

Pointer to a rectangle (or NULL).

Prototype:

virtual int getUpdateRect(RECT *rp) = 0;

Remarks:

This method retrieves the current update rectangle.

Parameters:

RECT *rp

The current update rectangle.

Return Value:

Zero if the update rectangle is invalid; otherwise nonzero.

Prototype:

virtual void setRndLimits(DWORD l) = 0;

Remarks:

Sets the rendering limits used by primitive calls.

Note: Setting the rendering limits is used in communication between the various parts of 3ds max that handle the display of objects. For example, setting this limit to GW_POLY_EDGES and then drawing a polygon won't result in a polygon drawn with edges. It only sets a flag that indicates the edge should be drawn.

What happens is as follows. Inside the upper level MAX, part of the code knows that polygon edges have been turned on. However this is not related through the object oriented architecture to the part of 3ds max that does the actual drawing. When 3ds max goes to draw objects it will see that the polygon edge flag is on. This tells it to do two drawing passed -- one to do the polygon, then it calls outlinePass() call with TRUE, draws a bunch of edges, then calls outline Pass() with FALSE. Thus, the drawing routine is responsible for looking at the flags and drawing appropriately. This method is only responsible setting the limit which can later be checked.

Parameters:

DWORD l

Specifies the rendering limit used by the viewport. See Rendering Limits.

Prototype:

virtual DWORD getRndLimits() = 0;

Remarks:

Retrieves the rendering limits used by primitive calls. See Rendering Limits.

Prototype:

virtual DWORD getRndMode() = 0;

Remarks:

Returns the current rendering mode used by the viewport. This is a subset of the rendering limit, in that any limits imposed by the rendering limit are forced onto the current mode. See Rendering Limits.

Prototype:

virtual int getMaxStripLength();

Remarks:

This method is available in release 2.0 and later only.

This method returns the largest number of triangles that can be in a strip

Prototype:

virtual void setSkipCount(int n) = 0;

Remarks:

Sets the number of triangles skipped when the viewport is set as a 'Fast View Display' viewport. To disable fastview, specify 1. Note that the GraphicsWindow class doesn't actually do anything with this number other than store it. Since triangles are handed down to GFX one at a time, it is up to the code that feeds triangles to the GraphicsWindow to skip the specified number of triangles. The mesh rendering in 3ds max uses the skip count in this way.

Parameters:

int n

Specifies that every 'n-th' triangle should be drawn. If set to 2, every other triangle should be drawn.

Prototype:

virtual int getSkipCount() = 0;

Remarks:

Returns the current skip count setting.

Light and Camera Methods

Prototype:

virtual int getMaxLights() = 0;

Remarks:

Returns the maximum number of lights that may be used by the interactive renderer.

Prototype:

virtual void setLight(int num, const Light *l) = 0;

Remarks:

Turns a light on or off, and sets the light parameters. The light's position is set through the current transformation matrix at the time of this call. A particular light is specified by its light number (-1 through getMaxLights()-1). Light number -1 is reserved for ambient light. If a particular field in the Light class is not needed for a particular type of light, that field's value is ignored (for example, only the color field is used for ambient light.)

Parameters:

int num

The light number of the light to set. This is a value in the range -1 to getMaxLights()-1.

const Light *l

The light class instance used to set the light parameters. If this is NULL, the light is turned off.

Prototype:

virtual void setLightExclusion(DWORD exclVec) = 0;

Remarks:

This allows a developer to control if a light is used to render an object. There is one bit per light (bits 0 through getMaxLights()). If the bit is set the light is NOT used to render the object. If the bit is off, the light IS used. This method allows you to set the exclusion vector controlling the lights.

Parameters:

DWORD exclVec

The exclusion vector controlling the lights.

Prototype:

virtual void setCamera(const Camera &c) = 0;

Remarks:

This method is no longer used.

Prototype:

virtual void setCameraMatrix(float mat[4][4], Matrix3 *invTM, int persp, float hither, float yon) = 0;

Remarks:

Sets the properties of the current camera used by the GraphicsWindow.

Parameters:

float mat[4][4]

The transformation matrix times the projection matrix.

Matrix3 *invTM

This is the inverse of the affine part of the camera transformation matrix (not the inverse of the projection part).

int persp

Nonzero indicates this is a perspective view; 0 is orthogonal.

float hither

Near clip value.

float yon

Far clip value.

Prototype:

virtual void getCameraMatrix(float mat[4][4], Matrix3 *invTM, int *persp, float *hither, float *yon) = 0;

Remarks:

Retrieves the properties of the current camera.

Parameters:

float mat[4][4]

The transformation matrix times the projection matrix.

Matrix3 *invTM

This is the inverse of the affine part of the camera transformation matrix (not the inverse of the projection part).

int *persp

Nonzero indicates this is a perspective view; 0 is orthogonal.

float *hither

Near clip value.

float *yon

Far clip value.

Material Methods

Prototype:

virtual void setMaterial(const Material &m, int index=0) = 0;

Remarks:

Sets the current rendering material, and modifies the rendering mode parameter for controlling the rasterizer driver. Note: You must have your rendering limit set BEFORE you set the material because the material setting may lower the rendering mode based on the material limits.

Parameters:

const Material &m

The new material to instantiate

int index=0

Indicates which material index refers to the material which gets set.

Prototype:

virtual Material *getMaterial() = 0;

Remarks:

Returns the current rendering material.

Prototype:

virtual void setTransparency(DWORD settings) = 0;

Remarks:

Sets the current transparency flags for the current pass.

Parameters:

DWORD settings

This can be a combination if GW_TRANSPARENCY and GW_TRANSPARENT_PASS See Rendering Limits. You also use these settings in the Render limits as well.

Coordinate Transformation Methods

Prototype:

virtual DWORD hTransPoint(const Point3 *in, IPoint3 *out) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method converts coordinates to "h" format device coordinates. Note: This method maps points from the GraphicsWindow's current transform to device space. If the GraphicsWindow's transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the GraphicsWindow transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the transform to the identity with gw->setTransform(Matrix3(1)).

Parameters:

const Point3 *in

The input point.

IPoint3 *out

The output point in integer format values in the native device coords for the device. For HEIDI and OpenGL the origin at the lower left. For Direct3D the origin is at the upper left.

Return Value:

DWORD containing the clipping flags for the point. If a flag is set it indicates the transformed point lies outside the view volume. See List of Clip Flags.

Prototype:

virtual DWORD wTransPoint(const Point3 *in, IPoint3 *out) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used to convert coordinates to "w" format device coordinates. Note: This method maps points from the GraphicsWindow's current transform to device space. If the GraphicsWindow's transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the GraphicsWindow transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the transform to the identity with gw->setTransform(Matrix3(1)).

Parameters:

const Point3 *in

The input point.

IPoint3 *out

The output point in integer format with the origin at the upper left.

Return Value:

DWORD containing the clipping flags for the point. If a flag is set it indicates the transformed point lies outside the view volume. See List of Clip Flags.

Prototype:

virtual DWORD transPoint(const Point3 *in, Point3 *out) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used to convert coordinates to "h" floating point coordinates. This is just a helper routine to avoid building up round-off error. 3ds max uses it just for IK. Note: This method maps points from the GraphicsWindow's current transform to device space. If the GraphicsWindow's transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the GraphicsWindow transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the transform to the identity with gw->setTransform(Matrix3(1)).

Parameters:

const Point3 *in

The input point.

Point3 *out

The output point in floating point format with the origin at the lower left.

Return Value:

DWORD containing the clipping flags for the point. If a flag is set it indicates the transformed point lies outside the view volume. See List of Clip Flags.

Drawing Methods

Note: The old device coordinate calls have been changed (or removed). In 3ds max 2.0 and later, methods that start with "h" take integer device coordinates with the origin at the lower-left. Calls with a "w" in front take Windows device coordinates with the origin at the upper left. Also Note: These "h" and "w" routines perform NO clipping unless otherwise noted (clipping at this level would be very expensive). Drawing outside the allowable region is likely to cause 3ds max to crash.

Prototype:

virtual void hText(IPoint3 *xyz, TCHAR *s) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws 2D fixed font annotation text to the specified location. Note: This routine DOES perform clipping of the text if it is off the screen.

Parameters:

IPoint3 *xyz

This is the device coordinate for the text. The origin of the text is at the lower left corner.

TCHAR *s

The text to display.

Prototype:

virtual void hMarker(IPoint3 *xyz, MarkerType type) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws a marker at the specified location.

Parameters:

IPoint3 *xyz

This is the device coordinate for the marker (with the origin at the lower left).

MarkerType type

See List of Marker Types.

Prototype:

virtual void hPolyline(int ct, IPoint3 *xyz, Point3 *rgb, int closed, int *es) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-segment polyline.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the lower left.

Point3 *rgb

If the shade mode is set to smooth and these colors for the vertices are specified the polyline will be drawn Gourand shaded. This is how 3ds max draws lit wireframes for instance. If you simply want ordinary lines (drawn using the line color) pass NULL.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

void hPolyline(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw, int closed, int *es);

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-segment polyline.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the lower left.

Point3 *rgb

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

This is not currently used. Pass NULL.

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

virtual void hPolygon(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-point polygon.

Parameters:

int ct

The number of points in the polygon.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the lower left.

Point3 *rgb

The color values at the vertices. The rendering mode must include GW_ILLUM for these values to be used.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW coordinates. The rendering mode must include GW_TEXTURE for these values to be used.

Prototype:

virtual void hTriStrip(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used for drawing a series of triangles specified as 'strips'. It takes a count of 3 or more, and builds triangles in a strip. This sends a lot less data and the underlying graphics library has to set up a lot less data since it can use the previous information to start the rasterization. This results in a significant speed increase.

Note that this routine does no clipping so all the points passed must be within view.

Parameters:

int ct

The total number of points. After the first two points, each new point is used to create a new triangle.

IPoint3 *xyz

The point data with the origin at the lower left. For instance, to draw a quad, the first three points specify the first triangle and the next one is combined with the previous two to complete the square.

The order for these points follows the 'standard' conventions for stripping used in most graphics libraries (for example Direct3D, OpenGL and Heidi).

Point3 *rgb

The colors for the vertices.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW texture coordinates for the vertices.

Prototype:

virtual void wText(IPoint3 *xyz, TCHAR *s) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws 2D fixed font annotation text to the specified location. Note: This routine DOES perform clipping of the text if it is off the screen.

Parameters:

IPoint3 *xyz

This is the device coordinate for the text. The origin of the text is at the upper left corner.

TCHAR *s

The text to display.

Prototype:

virtual void wMarker(IPoint3 *xyz, MarkerType type) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws a marker at the specified location.

Parameters:

IPoint3 *xyz

This is the device coordinate for the marker.

MarkerType type

See List of Marker Types.

Prototype:

virtual void wPolyline(int ct, IPoint3 *xyz, Point3 *rgb, int closed, int *es) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-segment polyline.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the upper left.

Point3 *rgb

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

void wPolyline(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw, int closed, int *es);

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-segment polyline.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the upper left.

Point3 *rgb

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

This is not currently used. Pass NULL.

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

virtual void wPolygon(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a multi-point polygon.

Parameters:

int ct

The number of points in the polygon.

IPoint3 *xyz

Array of points. These are device coordinates with the origin at the upper left.

Point3 *rgb

The color values at the vertices. The rendering mode must include GW_ILLUM for these values to be used.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW coordinates. The rendering mode must include GW_TEXTURE for these values to be used.

Prototype:

virtual void wTriStrip(int ct, IPoint3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

Note that this routine does no clipping so all the points passed must be within view.

Parameters:

int ct

The total number of points. After the first two points, each new point is used to create a new triangle.

IPoint3 *xyz

The point data with the origin at the upper left. For instance, to draw a quad, the first three points specify the first triangle and the next one is combined with the previous two to complete the square.

The order for these points follows the 'standard' conventions for stripping used in most graphics libraries (for example Direct3D, OpenGL and Heidi).

Point3 *rgb

The colors for the vertices.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW texture coordinates for the vertices.

Prototype:

virtual void text(Point3 *xyz, TCHAR *s) = 0;

Remarks:

Draws 2D fixed font annotation text to the specified location. This method does perform clipping.

Note: This method maps points from the GraphicsWindow's current transform to screen space. If the GraphicsWindow's transform is set to the identity matrix then the mapping is done from points specified in world space. Otherwise the points given are transformed by the GraphicsWindow transform, and are then considered to be in world space. Thus, to get a world-space to screen-space conversion, you need to set the transform to the identity with gw->setTransform(Matrix3(1)).

Parameters:

Point3 *xyz

This is the coordinate for the text.

TCHAR *s

The text to display. Note: This routine DOES perform clipping of the text if it is off the screen.

Prototype:

virtual void marker(Point3 *xyz, MarkerType type) = 0;

Remarks:

Draws a marker at the specified location in world space. This method does perform clipping.

Parameters:

Point3 *xyz

This is the coordinate for the marker.

MarkerType type

See List of Marker Types.

Prototype:

virtual void polyline(int ct, Point3 *xyz, Point3 *rgb, Point3 *uvw, int closed, int *es) = 0;

Remarks:

Draws a multi-segment polyline with the coordinates specified in world space. This method does perform clipping.

Note: The arrays of points and vertex related data all must be at least one element larger than the ct parameter that is passed in. The 3D clipper will use the "extra" space to clip as efficiently as possible. If room for the extra element is not provided, 3ds max may crash.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

Point3 *xyz

Array of points. This array must be at least one element larger than the ct parameter that is passed in. The 3D clipper will use the "extra" space to clip as efficiently as possible. If room for the extra element is not provided, 3ds max will crash.

Point3 *rgb

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

This is not currently used. Pass NULL.

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

virtual void polylineN(int ct, Point3 *xyz, Point3 *nor, int closed, int *es) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws a multi-segment polyline with the coordinates specified in world space. This method takes a polyline with a normal for each vertex. This is used for hardware accelerated lit wireframes (when GW_SPT_GEOM_ACCEL is TRUE).

This method does perform clipping.

Parameters:

int ct

The number of points in the polyline. The maximum number of points that may be used in drawing a polyline is 32.

Point3 *xyz

Point3 *nor

The normal values at the vertices, one for each vertex.

int closed

If nonzero the first point is connected to the last point, i.e. the polyline is closed.

int *es

Edge state array. This is an array that Indicates if the 'i-th' edge is one of three state:

GW_EDGE_SKIP

Nonexistent - totally invisible.

GW_EDGE_VIS

Exists and is solid.

GW_EDGE_INVIS

Exists and is hidden - shown as a dotted line.

You may pass NULL for this array and the method will assume that the edges are all solid.

Prototype:

virtual void polygon(int ct, Point3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

Draws a multi-point polygon. Note: All arrays (xyz, rgb, uvw) must be at least one element larger than the ct parameter that is passed in. The 3D clipper will use the "extra" space to clip as efficiently as possible. If room for the extra element is not provided, 3ds max may crash.

Parameters:

int ct

The number of points in the polygon.

Point3 *xyz

Array of points.

Point3 *rgb

The color values at the vertices. The rendering mode must include GW_ILLUM for these values to be used.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW coordinates. The rendering mode must include GW_TEXTURE for these values to be used.

Prototype:

virtual void startSegments() = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is used to begin efficiently sending a lot of 3D line segments. First call this method, then call segment() many times (with two points), then call endSegments().

Prototype:

virtual void segment(Point3 *xyz, int vis) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a single 3D line segment between the specified points. Call startSegments() once before calling this method.

Parameters:

Point3 *xyz

Points to the two line endpoints in world space.

int vis

Nonzero for the segment to be visible; zero for invisible.

Prototype:

virtual void endSegments() = 0;

Remarks:

This method is available in release 2.0 and later only.

Call this method after sending 3D line segments with segment().

Prototype:

virtual void polygonN(int ct, Point3 *xyz, Point3 *nor, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

Draws a multi-point polygon. Note: All arrays (xyz, nor, uvw) must be at least one element larger than the ct parameter that is passed in. The 3D clipper will use the "extra" space to clip as efficiently as possible. If room for the extra element is not provided, 3ds max will crash.

This method sends in normal vectors instead of color for 3D accelerated rendering (when GW_SPT_GEOM_ACCEL is TRUE)

Parameters:

int ct

The number of points in the polygon.

Point3 *xyz

Array of points.

Point3 *nor

The normal values at the vertices, one for each vertex.

Point3 *uvw

The UVW coordinates. The rendering mode must include GW_TEXTURE for these values to be used.

Prototype:

virtual void triStrip(int ct, Point3 *xyz, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

Parameters:

int ct

The total number of points. After the first two points, each new point is used to create a new triangle.

IPoint3 *xyz

The point data. For instance, to draw a quad, the first three points specify the first triangle and the next one is combined with the previous two to complete the square.

The order for these points follows the 'standard' conventions for stripping used in most graphics libraries (for example Direct3D, OpenGL and Heidi).

Point3 *rgb

The colors for the vertices.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Point3 *uvw

The UVW texture coordinates for the vertices.

Prototype:

virtual void triStripN(int ct, Point3 *xyz, Point3 *nor, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

Parameters:

int ct

The total number of points. After the first two points, each new point is used to create a new triangle.

Point3 *xyz

The point data. For instance, to draw a quad, the first three points specify the first triangle and the next one is combined with the previous two to complete the square.

The order for these points follows the 'standard' conventions for stripping used in most graphics libraries (for example Direct3D, OpenGL and Heidi).

Point3 *nor

The normal for each vertex.

Point3 *uvw

The UVW texture coordinates for the vertices.

Prototype:

virtual void startTriangles() = 0;

Remarks:

This method is available in release 2.0 and later only.

This method is called to begin sending a series of non-stripped triangles to render. Call this method, then any of the triangle*() methods many times, then endTriangles() to finish.

Prototype:

virtual void triangle(Point3 *xyz, Point3 *rgb) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method sends a single non-stripped triangle to render. Call startTriangles() first.

Parameters:

Point3 *xyz

The three points for the triangle.

Point3 *rgb

The color for each vertex.

Note: The use of these colors is not supported under the OpenGL driver. The rgb values are ignored. Only the current material is taken into consideration. (This is how OpenGL works.)

Prototype:

virtual void triangleN(Point3 *xyz, Point3 *nor, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a single triangle by specifying the vertex points in world space, a normal, and texture coordinates for each vertex.

Parameters:

Point3 *xyz

The three points for the triangle.

Point3 *nor

The three normals for the triangle.

Point3 *uvw

The texture coordinate for each vertex.

Prototype:

virtual void triangleNC(Point3 *xyz, Point3 *nor, Point3 *rgb) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a single triangle by specifying the vertex points in world space, a normal, and a color for each vertex.

Parameters:

Point3 *xyz

The three points for the triangle.

Point3 *nor

The normal for each vertex.

Point3 *rgb

The color for each vertex.

Prototype:

virtual void triangleNCT(Point3 *xyz, Point3 *nor, Point3 *rgb, Point3 *uvw) = 0;

Remarks:

This method is available in release 2.0 and later only.

This method draws a single triangle by specifying the vertex points in world space, a normal, a color, and a texture coordinate for each vertex.

Parameters:

Point3 *xyz

The three points for the triangle.

Point3 *nor

The normal for each vertex.

Point3 *rgb

The color for each vertex.

Point3 *uvw

The texture coordinate for each vertex.

Prototype:

virtual void endTriangles() = 0;

Remarks:

This method is available in release 2.0 and later only.

Call this method to finish rendering triangles. See startTriangles() above.

Prototype:

virtual void lightVertex(const Point3 &pos, const Point3 &nor, Point3 &rgb) = 0;

Remarks:

Lights a vertex, using all the current lights. The vertex appears to be transformed using the current transformation matrix, although actually the calculations are done using back-transformed light coordinates (for speed). The vertex position and normal are passed in, and a color is returned. The rendering uses the current material.

Parameters:

const Point3 &pos

Vertex position.

const Point3 &nor

Vertex normal.

Point3 &rgb

Returned color.

Prototype:

virtual void updateScreen() = 0;

Remarks:

This method is used internally and should not be called by plug-in developers.

Prototype:

virtual void setColor(ColorType t, float r, float g, float b) = 0;

Remarks:

Sets the RGB color used for the specified drawing type (line, fill, text, clear).

Parameters:

ColorType t

One of the following values:

LINE_COLOR

Line drawing color.

FILL_COLOR

Polygon fill color.

TEXT_COLOR

Text drawing color.

CLEAR_COLOR

The color that the viewport is cleared to when you call clearScreen().

float r

Specifies the red amount 0.0 - 1.0.

float g

Specifies the green amount 0.0 - 1.0.

float b

Specifies the blue amount 0.0 - 1.0.

Prototype:

virtual void clearScreen(RECT *rp, int useBkg = FALSE) = 0;

Remarks:

Clears the specified rectangular region of the screen.

Parameters:

RECT *rp

Specifies the rectangular region to clear.

int useBkg = FALSE

Specifies if the background should be used to fill the cleared area. Nonzero indicate the background should be used; 0 indicates the 'clear' color should be used (see setColor() above).

Hit Testing Methods

The following methods are used for hit testing. Typically you use these methods in the following sequence:

$image\bullet.gif$ You set a hit regions using setHitRegion().

$image\bullet.gif$ You clear the hit code using clearHitCode().

$image\bullet.gif$ You 'render' a primitive using the mode GW_PICK and at whatever level you want to check at. For example, if you are in interested in vertex hit testing, you would 'render' a series of markers (using iWinMarker() with PLUS_SIGN_MRKR) using a rendering mode that included GW_PICK. The GW_PICK 'rendering' mode will cause the system to perform hit testing rather than actually render the item.

$image\bullet.gif$ After each item is 'rendered' you check to see if a hit was made using checkHitCode(). This method returns TRUE of FALSE based on if a hit was found. If you are looking for just a single hit, you could abort as soon as checkHitCode() returns TRUE. If you are interested in the closest hit, you loop through all the items calling clearHitCode(), checkHitCode() and getHitDistance(). After checking all the items you simply choose the smallest hit distance from all the items you've checked.

Prototype:

virtual void setHitRegion(HitRegion *rgn) = 0;

Remarks:

Sets the hit region used for hit testing. See Class HitRegion.

Parameters:

HitRegion *rgn

The hit region to use.

Prototype:

virtual void clearHitCode() = 0;

Remarks:

This methods clears the hit code. Call this method before performing a hit test.

Prototype:

virtual BOOL checkHitCode() = 0;

Remarks:

Returns TRUE if the hit code is set indicating a hit was made; otherwise FALSE.

Prototype:

virtual DWORD getHitDistance() = 0;

Remarks:

If checkHitCode() returns TRUE you may call this method to return the hit distance. In wireframe mode this is the distance to the line. In shaded mode, this is the z distance. This allows you to perform 'smart' hit testing by choosing the item with the smallest hit distance. This method only returns meaningful values when the hit region is a point.

Prototype:

virtual void setHitCode(BOOL h)=0;

Remarks:

This method is available in release 4.0 and later only.

This method allows drawing code to manually set the state of the hit code, which is returned by the checkHitCode() method. For more information see the topic on Hit Testing.

The new methods setHitDistance() and setHitCode() make it possible to work with GraphicsWindow hit-testing in otherwise impossible situations. Why are they necessary? An example from is shown below. The patch object contains bezier spline-based edges which can consist of up to 102 vertices. Since the GraphicsWindow::polyline function can only plot lines with up to 32 vertices, it is impossible to plot these in a single call to the polyline function. Multiple calls to the polyline call do not return a proper hitcode when using a "window"-type hit region. By using the new setHitCode() method, code can properly handle this situation. The code below shows the function in use from the PatchMesh::renderEdge method:

int steps = GetMeshSteps();

int segNum = steps+2;

float fsegNum = (float) (segNum-1);

// If steps are too high for GraphicsWindow's buffer, we must draw it manually

if((steps + 2) > GW_MAX_VERTS) {

Point3 line[2];

Point3 prev,current(.0f,.0f,.0f);

BOOL hitAll = TRUE;

BOOL hitAny = FALSE;

DWORD hitDist = 0xffffffff;

for(int terp = 0; terp < segNum; terp++)

{

prev = current;

current = work.InterpCurve3D((float)terp / fsegNum);

if (terp != 0)

{

line[0] = prev;

line[1] = current;

gw->clearHitCode();

gw->polyline(2, line, NULL, NULL, 0, NULL);

if(gw->checkHitCode()) {

hitAny = TRUE;

if(gw->getHitDistance() < hitDist)

hitDist = gw->getHitDistance();

}

else hitAll = FALSE;

}

if(hr && !hr->crossing && hr->type != POINT_RGN)

gw->setHitCode(hitAll);

else

gw->setHitCode(hitAny);

gw->setHitDistance(hitDist);

} else {

for(int terp = 0; terp < segNum; terp++)

fixedBuf[terp] = work.InterpCurve3D((float)terp / fsegNum);

gw->polyline(steps+2, fixedBuf, NULL, NULL, 0, NULL);

}

Note that the gw->polyline call is preceded by a call to clearHitCode(), and followed by code which checks the hit code, maintaining "hitAny" and "hitAll" flags. When all the segments are drawn, the gw->setHitCode() call is made, setting the hit code depending on the hit region type. When the code which called this function checks the GraphicsWindow�s hit code, it will contain the proper value. This code also keeps track of the closest hit distance and places that into the GraphicsWindow when all line segments are drawn.

Parameters:

BOOL h

Set to TRUE if the hit code is set, otherwise FALSE.

Prototype:

virtual void setHitDistance(DWORD d)=0;

Remarks:

This method is available in release 4.0 and later only.

This method allows drawing code to manually set the hit distance, which is returned by the getHitDistance() method. For more information see the topic on Hit Testing.

Parameters:

DWORD d

In wireframe mode this is the distance to the line. In shaded mode, this is the z distance.

Prototype:

virtual float interpWorld(Point3 *world1, Point3 *world2, float sParam, Point3 *interpPt) = 0;

Remarks:

This method is used internally.

Utility Functions (not part of class GraphicsWindows):

Function:

GraphicsWindow *createGW(HWND hWnd, GWinSetup &gws);

Remarks:

This function is used internally to create a new graphics window. Use of this method is not supported for plug-ins.

Function:

void getRegionRect(HitRegion *hr, RECT *rect);

Remarks:

Returns a bounding rectangle that encloses the entire hit region. For example if the hit regions was a fence region, this method would return the smallest rectangle that included the entire set of fence region points.

Parameters:

HitRegion *hr

The hit region to check.

RECT *rect

The returned bounding rectangle.

Function:

BOOL pointInRegion(int x, int y, HitRegion *hr);

Remarks:

Returns TRUE if the specified point is inside the region hr; otherwise FALSE.

Function:

int distToLine(int x, int y, int *p1, int *p2);

Remarks:

Returns the signed distance from x,y to the line defined by p1->p2.

Function:

int lineCrossesRect(RECT *rc, int *p1, int *p2);

Remarks:

Returns nonzero if the line defined by p1->p2 crosses into the RECT and 0 otherwise.

Function:

int segCrossesCircle(int cx, int cy, int r, int *p1, int *p2);

Remarks:

Returns nonzero if the line defined by p1->p2 crosses the circle center at (cx, cy) with a radius of r 0 otherwise.

Function:

BOOL insideTriangle(IPoint3 &p0, IPoint3 &p1, IPoint3 &p2, IPoint3 &q);

Remarks:

Returns TRUE if the point passed is inside the specified triangle.

Parameters:

IPoint3 &p0

The first point of the triangle.

IPoint3 &p1

The second point of the triangle.

IPoint3 &p2

The third point of the triangle.

IPoint3 &q

The point to check.

Return Value:

Returns TRUE if the point passed is inside the specified triangle; otherwise FALSE.

Function:

int getZfromTriangle(IPoint3 &p0, IPoint3 &p1, IPoint3 &p2, IPoint3 &q);

Remarks:

Returns the z value of where the projected screen point q would intersect the triangle defined by (p0, p1, p2).

Parameters:

IPoint3 &p0

The first point of the triangle.

IPoint3 &p1

The second point of the triangle.

IPoint3 &p2

The third point of the triangle.

IPoint3 &q

The screen point to check.

Prototype:

HINSTANCE GetGraphicsLibHandle(TCHAR *driverLibName);

Remarks:

This function is available in release 2.0 and later only.

This function is not supported for use in the SDK.

Prototype:

BOOL GraphicsSystemIsAvailable(HINSTANCE drv);

Remarks:

This function is available in release 2.0 and later only.

This function is not supported for use in the SDK.

Prototype:

BOOL GraphicsSystemCanConfigure(HINSTANCE drv);

Remarks:

This function is available in release 2.0 and later only.

This function is not supported for use in the SDK.

Prototype:

BOOL GraphicsSystemConfigure(HWND hWnd, HINSTANCE drv);

Remarks:

This function is available in release 2.0 and later only.

This function is not supported for use in the SDK.

Prototype:

void FreeGraphicsLibHandle(HINSTANCE drv);

Remarks:

This function is available in release 2.0 and later only.

This function is not supported for use in the SDK.

previous page start next page