GPort Class Reference

#include <gport.h>

Class Description

See also

Advanced Topics on Color Palettes, Class Color, Class GammaMgr, COLORREF.

Description:

A useful utility class for managing user interface colors. This class has several purposes:

Maintain the default 3ds Max palette for doing 256 color graphics.

Provides a mechanism for allocating "animated color slots" in the default palette for use in the user interface.

Provide various functions for doing dithered graphics using the default 3ds Max palette.

All methods of this class are implemented by the system.

The following global function is used to get a pointer that may be used to call the methods of this class:

Inheritance diagram for GPort:

Public Member Functions
virtual	~GPort ()
virtual int	AnimPalIndex (int i)=0
virtual int	GetAnimPalSlot ()=0
virtual void	ReleaseAnimPalSlot (int i)=0
virtual void	SetAnimPalEntry (int i, COLORREF cr)=0
virtual HPALETTE	PlugPalette (HDC hdc)=0
virtual HBRUSH	MakeAnimBrush (int slotNum, COLORREF col)=0
virtual int	UpdateColors (HDC hdc)=0
virtual void	AnimPalette (HDC hdc)=0
virtual void	RestorePalette (HDC hDC, HPALETTE hOldPal)=0
virtual void	MapPixels (UBYTE *inp, UBYTE *outp, int x, int y, int width)=0
virtual void	DisplayMap (HDC hdc, Rect &drect, int xsrc, int ysrc, UBYTE *map, int bytesPerRow)=0
virtual void	DisplayMap (HDC hdc, Rect &dest, Rect &src, UBYTE *map, int bytesPerRow)=0
virtual void	DitherColorSwatch (HDC hdc, Rect &r, Color c)=0
virtual void	PaintAnimPalSwatch (HDC hdc, DWORD col, int slot, int left, int top, int right, int bottom)=0
virtual HPALETTE	GetPalette ()=0

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_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...

Constructor & Destructor Documentation

virtual ~GPort ( )

inlinevirtual

Remarks

Destructor

{;}

Member Function Documentation

virtual int AnimPalIndex ( int  i )

pure virtual

Remarks

Retrieves the palette index associated with the 'i-th' slot.

Parameters:

int i

Specifies the slot.

virtual int GetAnimPalSlot ( )

pure virtual

Remarks

Returns a slot number if available, -1 if not. Typically this is called in WM_INITDIALOG processing code for as many slots as you need (the total number available is 8).

Returns

A slot number if available; otherwise -1.

virtual void ReleaseAnimPalSlot ( int  i )

pure virtual

Remarks

Releases the specified animated palette slot. Typically this is called in the WM_DESTROY code for each slot obtained with GetAnimPalSlot().

Parameters:

int i

The palette slot to release.

virtual void SetAnimPalEntry ( int  i, COLORREF  cr  )

pure virtual

Remarks

Sets the color associated with the 'i-th' animated slot.

Parameters:

int i

The slot index.

COLORREF cr

The color to set.

virtual HPALETTE PlugPalette ( HDC  hdc )

pure virtual

Remarks

This method puts the standard 3ds Max palette into the palette for the HDC, handing back a handle to the old palette.

Parameters:

HDC hdc

The device context.

Returns

The handle of the old palette.

virtual HBRUSH MakeAnimBrush ( int  slotNum, COLORREF  col  )

pure virtual

Remarks

This method creates a brush for drawing with the specified animated palette slot color.

Parameters:

int slotNum

The animated palette slot.

COLORREF col

The color to use.

Returns

The handle of the brush created.

virtual int UpdateColors ( HDC  hdc )

pure virtual

Remarks

This method calls the Windows API UpdateColors() on the specified device context handle hdc. Call this when you get a WM_PALETTECHANGED message.

Parameters:

HDC hdc

The handle of the device context.

Returns

Nonzero if it changed screen pixel values; otherwise zero.

virtual void AnimPalette ( HDC  hdc )

pure virtual

Remarks

After several calls to SetAnimPalEntry(), call this to affect the HDC's palette. This puts the palette into the HDC so it will take effect.

Parameters:

HDC hdc

The handle of the device context.

virtual void RestorePalette ( HDC  hDC, HPALETTE  hOldPal  )

pure virtual

Remarks

This method puts the previous 3ds Max palette (returned from PlugPalette()) into the palette for the HDC.

Parameters:

HDC hDC

The handle of the device context.

HPALETTE hOldPal

The palette to restore.

virtual void MapPixels ( UBYTE *  inp, UBYTE *  outp, int  x, int  y, int  width  )

pure virtual

Remarks

This method maps a single row of pixels in 24 bit color to indices into the current GPort palette, applying a dither pattern. This routine does NOT do gamma correction.

Note that x and y are necessary to establish the dither pattern alignment. The dither pattern covers the entire map, and if you want to just dither part of it, you need to tell this method where you are within the pattern.

Parameters:

UBYTE* inp

Points to an array of width BGR triples. This is a sequence of bytes structured as B,G,R,B,G R, etc. The first pixel is B,G,R then the next pixel is B,G,R, etc.

UBYTE *outp

The result - the color indices into the GPort palette. This array is width bytes in length.

int x

The x alignment position.

int y

The y alignment position.

int width

The number of items in the arrays above.

virtual void DisplayMap ( HDC  hdc, Rect &  drect, int  xsrc, int  ysrc, UBYTE *  map, int  bytesPerRow  )

pure virtual

Remarks

Display an array of 24 bit colors in the HDC. If the current display is 8 bit it will display it (with dither) using in the GPort palette, otherwise it will just blit to the screen. This method does NOT do gamma correction.

Parameters:

HDC hdc

The handle of the device context.

Rect& drect

The destination rectangle in the hdc.

int xsrc

The X position within this source raster of the upper left corner of the rectangle to be copied.

int ysrc

The Y position within this source raster of the upper left corner of the rectangle to be copied.

UBYTE *map

Points to an array of BGR triples.

int bytesPerRow

The number of bytes per row on each scanline of map.

virtual void DisplayMap ( HDC  hdc, Rect &  dest, Rect &  src, UBYTE *  map, int  bytesPerRow  )

pure virtual

Remarks

This version of DisplayMap() stretches the image if the source rectangle is not the same size as the destination rectangle. src should be the size of the image.

Parameters:

HDC hdc

The handle of the device context.

Rect& dest

The destination rectangle in the hdc.

Rect& src

The source rectangle in map.

UBYTE *map

Points to an array of RGB triples.

int bytesPerRow

The number of bytes per row on each scanline of map.

virtual void DitherColorSwatch ( HDC  hdc, Rect &  r, Color  c  )

pure virtual

Remarks

This method first gamma corrects Color c using the current display gamma. In paletted modes, it will fill rectangle r with a dithered pattern approximating Color c. In 24 bit modes it just fills the rectangle with Color c.

Parameters:

HDC hdc

The handle of the device context.

Rect& r

The rectangle to fill.

Color c

The color to approximate (8 bit) or fill with (24 bit).

virtual void PaintAnimPalSwatch ( HDC  hdc, DWORD  col, int  slot, int  left, int  top, int  right, int  bottom  )

pure virtual

Remarks

This method attempts to use the animated color slot indicated by "slot" to paint a rectangular color swatch. If slot is -1, it will uses DitherColorSwatch(). This method does handle gamma correction.

Parameters:

HDC hdc

The handle of the device context.

DWORD col

The color to paint. The format is the same as COLORREF.

int slot

Specifies the slot to use. If -1 then DitherColorSwatch() is used.

int left

The left coordinate of the rectangular area to paint.

int top

The top coordinate of the rectangular area to paint.

int right

The right coordinate of the rectangular area to paint.

int bottom

The bottom coordinate of the rectangular area to paint.

virtual HPALETTE GetPalette ( )

pure virtual

Remarks

Returns the current GPort palette.