Class GPort
See Also: Advanced Topics on Palettes, Class Color, Class GammaMgr, COLORREF.
class GPort
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:
Prototype:
GPort* GetGPort();
Remarks:
There is only a single global instance of this class, and this method returns a pointer to it. A developer may use this pointer to call the methods of GPort.
Sample Code:
int animColSlot = GetGPort()->GetAnimPalSlot();
Methods:
Prototype:
virtual int GetAnimPalSlot()=0;
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).
Return Value:
A slot number if available; otherwise -1.
Prototype:
virtual int AnimPalIndex(int i)=0;
Remarks:
Retrieves the palette index associated with the 'i-th' slot.
Parameters:
int i
Specifies the slot.
Prototype:
virtual void ReleaseAnimPalSlot(int i)=0;
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.
Prototype:
virtual void SetAnimPalEntry(int i, COLORREF cr)=0;
Remarks:
Sets the color associated with the 'i-th' animated slot.
Parameters:
int i
The slot index.
COLORREF cr
The color to set.
Prototype:
virtual void AnimPalette(HDC hdc)=0;
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.
Prototype:
virtual HPALETTE PlugPalette(HDC hdc)=0;
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.
Return Value:
The handle of the old palette.
Prototype:
virtual void RestorePalette(HDC hDC,HPALETTE hOldPal)=0;
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.
Prototype:
virtual HBRUSH MakeAnimBrush(int slotNum, COLORREF col )=0;
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.
Return Value:
The handle of the brush created.
Prototype:
virtual int UpdateColors(HDC hdc)=0;
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.
Return Value:
Nonzero if it changed screen pixel values; otherwise zero.
Prototype:
virtual void MapPixels(UBYTE* inp, UBYTE *outp, int x, int y, int width)=0;
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.
Prototype:
virtual void DisplayMap(HDC hdc, Rect& drect, int xsrc, int ysrc, UBYTE *map, int bytesPerRow)=0;
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.
Prototype:
virtual void DisplayMap(HDC hdc, Rect& dest, Rect& src, UBYTE *map, int bytesPerRow)=0;
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.
Prototype:
virtual void DitherColorSwatch(HDC hdc, Rect& r, Color c)=0;
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).
Prototype:
virtual void PaintAnimPalSwatch(HDC hdc, DWORD col, int slot, int left, int top, int right, int bottom)=0;
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.
Prototype:
virtual HPALETTE GetPalette()=0;
Remarks:
Returns the current GPort palette.
The following functions are not part of class GPort but are available for use
Prototype:
static inline void gammaCorrect(COLORREF& c)
Remarks:
Gamma corrects the specified color using the display gamma setting.
Parameters:
COLORREF& c
The color to gamma correct.
Prototype:
static inline void deGammaCorrect(COLORREF& c)
Remarks:
Reverses the effect of gamma correction on the specified color.
Parameters:
COLORREF& c
The color to de-gamma.