TypeServer MGBITMAPINFO Structure

The MGBITMAPINFO structure is used to define a graphics bitmap that TypeServer renders to. TypeServer can work with many different bitmap types and formats, including:

External bitmaps that have been created independently of TypeServer, such as a custom application-created bitmap or a bitmap created by another graphics library.
Video hardware bitmaps which are located at a predefined address in video memory.
TypeServer created bitmaps that your application may also directly access.

The procedures for defining various bitmap types is outlined in the "TypeServer Bitmaps" description within Chapter 4 of the TypeServer Programming Reference Manual.

typedef struct _MGBITMAPINFO
{
  INT32         structSize;  /* number of bytes in this struct            */
  UINT32        objectType;  /* fourCC object type identifier (='MGBI')   */
  INT32         pixWidth;    /* pixel width (pixels x, horizontally)      */
  INT32         pixHeight;   /* pixel height (pixels y, vertically)       */
  int           pixBits;     /* bits per pixel (1,2,4,8,15,16,24 or 32)   */
  int           pixBytes;    /* bytes per pixel (pixBits/8=0,1,2,3 or 4)  */
  int           pixPlanes;   /* number of planes per pixel (1 or 4)       */
  int           pixResX;     /* pixels per inch, horizontally             */
  int           pixResY;     /* pixels per inch, vertically               */
  int           rowBytes;    /* number of bytes in a single raster line   */
  int           pitch;       /* byte displacement between raster lines    */
  RECT          limitsRect;  /* limits rectangle (0,0,pixWidth,pixHeight) */
  int           rasterOp;    /* current rasterOp blit transfer mode       */
  void         *surface;     /* pointer to bitmap surface memory area     */
  void         *topY;        /* pointer to y=0 raster line                */
  MGCOLORRGB   *colorTable;  /* pointer to indexed RGB colorTable         */
  MGCOLORPIX    xparColor,   /* transparent color pixel value             */
  BOOL          transActive; /* TRUE if color translation is active       */
  BYTE         *transTable;  /* pointer to color translate table          */
  HDC           hdc;         /* handle to optional Windows DC             */
  HBITMAP       hbitmap;     /* handle to optional Windows BITMAP         */
  BITAMPINFO   *dibInfo;     /* ptr to optional Windows DIB BITMAPINFO    */
  MWGRAFPORT   *grafPort;    /* ptr to optional MetaWINDOW grafPort struc */
  MWGRAFMAP    *grafMap;     /* ptr to optional MetaWINDOW grafMap struct */
  BYTE        **rowTable[4]; /* ptr to raster rowTable address array(s)   */
  FIXDOT        fixResX;     /* pixels per inch, horizontal (fixed-point) */
  FIXDOT        fixResY;     /* pixels per inch, vertical (fixed-point)   */
} MGBITMAPINFO;

INT32 structSize
Size of this MGBITMAPINFO structure, in bytes.

UINT32 objectType
A FourCC 'MGBI' character code identifying an MGBITMAPINFO structure.

INT pixWidth
Bitmap pixel width (horizontal, X).

INT pixHeight
Bitmap pixel height (vertical, Y).

INT pixBits
Number of bits per pixel: 1 (2-color), 2 (4-color), 4 (16-color), 8 (256-color), 15 (32K-color), 16 (64K-color), 24 (16M-color) or 32 (16M-color+alpha).

INT pixBytes
Number of bytes per pixel (=pixBits/8 = 0, 1, 2, 3 or 4).

INT pixPlanes
Number of planes per pixel: 1, or 4 for VGA 16-color bitmaps (for 16-color VGA bitmaps pixBits=1 and pixPlanes=4, for anything else pixPlanes=1).

INT pixResX, PixResY
Number of pixels per inch, horizontal (X) and vertical (Y).

INT rowBytes
Number of bytes in a single raster line. Normally this is an even multiple of the native CPU word size to insure that raster lines begin on aligned memory boundaries. (For example, rowBytes is normally evenly divisible by 4 on 32-bit processors, or evenly divisible by 2 on 16-bit processors.) rowBytes is always a positive value.

INT pitch
pitch is the byte displacement between the start of one raster line to the beginning of the next. In some video modes, the separation between raster lines may be larger than rowBytes. For example, with certain display adapters 800x600 256-color modes have 800 bytes per raster line, but raster lines are separated at addresses of 1024 (a nice power of 2 for hardware simplicity). For this case, rowBytes would be set to 800, and pitch would be set to 1024.

pitch can either be positive or negative, depending if the bitmap is in a standard "top-down" format (positive), or special OS/2 style "bottom-up" format (negative). In a standard "top-down" bitmap, the first Y=0 raster line is located at the start of the bitmap surface area at a low memory address, with successive raster lines at increasing higher memory address locations. IBM OS/2, however, introduced a special reversed "bottom-up" style bitmap where the first y=0 raster line is at the end of the bitmap area, and successive raster lines occur at decreasing memory addresses. (For OS/2 "bottom-up" style bitmaps, the low memory address to the bitmap surface points to the last raster line instead of the first.) Although used infrequently, Microsoft Windows also supports "bottom-up" style bitmaps.

For OS/2 "bottom-up" style bitmaps, pitch is a negative byte displacement for moving between successive raster lines in decreasing memory address order (most "bottom-up" style bitmaps use "pitch = -rowbytes"). For standard "top-down" style bitmaps, pitch is a positive byte displacement for moving between successive raster lines in increasing memory address order (most "top-down" style bitmaps use "pitch = rowBytes").

RECT limitsRect
A RECT structure initialized with the pixel limits of the bitmap: (0,0,pixWidth,pixHeight).

INT rasterOp
Current rasterOp transfer mode (see MGRASTEROP enumeration).

void *surface
Low memory pointer to the start of the raster bitmap.

void *topY
Memory pointer to the starting Y=0 raster line. For standard "top-down" bitmaps, the topY and surface pointers are the same (topY = surface). For OS/2 style "bottom-up" bitmaps, the topY Y=0 raster line is the last line in the bitmap memory (normally, topY = surface + (pixHeight-1)*rowBytes).

MGCOLORRGB *colorTable
Used with 16- and 256-color indexed bitmaps only. colorTable points to an array of RGB values defining the colors for 16- or 256-indexed color bitmaps. Each value defines the actual RGB color associated with the corresponding pixel value. (For non color-indexed bitmaps with greater than 256-colors, the colorTable pointer is NULL.)

The size of the colorTable array is actually one greater than the number of colors in the bitmap. For a 16-color bitmap, colorTable contains 17 entries; for a 256-color bitmap, colorTable contains 257 entries. The one additional entry located at the end of the colorTable array is termed the "colorTable signature" or "CTSig". CTSig is a counter that is incremented each time any of the RGB values in the main colorTable array is changed. A change in CTSig is commonly used to identify when a dependent precomputed setting, such as a color translation table, must be recomputed after the colorTable array has been updated with one or more new RGB values.

MGCOLORPIX xparColor
Defines the transparent color when performing blit transfers with color transparency. The transparent color is set by calling the C mgBitmap_SetTransparentColor() function, or C++ mgCBitmap::SetTransparaentColor() method.

BOOL transActive
Used with indexed-color bitmaps (16- and 256-color) only. TRUE indicates that blit transfers are to be color translated to the destination bitmap's colorTable.

BYTE *transTable
Used with indexed-color bitmaps (16- and 256-color) only. transTable points to a pre-computed array for translating source bitmap pixel color indexes to destination bitmap pixel color indexes. This array is computed automatically by the blit functions when performing pixel transfers where the source and destination bitmaps have different RGB colorTable settings.

HDC hdc
Handle to optional Microsoft Windows "Device Context" associated with this bitmap.

BITMAPINFO *dibInfo
Pointer to optional Microsoft Windows BITMAPINFO structure associated with this bitmap.

MWGRAFPORT *grafPort
Pointer to optional MetaWINDOW grafPort structure associated with this bitmap.

MWGRAFMAP *grafMap
Pointer to optional MetaWINDOW grafMap structure associated with this bitmap.

BYTE **rowTable[4]
Pointer(s) to optional raster line rowTable address array(s).

FIXDOT fixResX
Pixels per inch, horizontal (fixed-point equivalent of pixResX).

FIXDOT fixResY
Pixels per inch, vertical (fixed-point equivalent of pixResY).