TypeServer QuickTour, Defining a Bitmap


Step 2 - Define a Target Bitmap

TypeServer needs to know where you want rasterized text to be drawn. TypeServer can draw either to an existing bitmap, such as a video frame buffer or an off-screen local memory bitmap previously created by your program, or can dynamically create a new bitmap that your application can also access.

Two functions are provided for defining bitmaps: mgBitmap_Create() and mgBitmap_CreateDirect(). mgBitmap_Create() provides extended controls for defining a wide range of special-case bitmap formats. mgBitmap_CreateDirect() is simpler to use and works with standard bitmap formats. Here are the C function prototypes for the two bitmap create functions:

 Header File Prototypes:
    MGEXTERN                      /* create a bitmap object (basic)            */
    MRESULT mgBitmap_CreateDirect(   /* return, completion code (0=success)    */
            int        pixWidth,     /* input,  pixels wide                    */
            int        pixHeight,    /* input,  pixels high                    */
            int        pixBits,      /* input,  bits per pixel                 */
            void      *surface,      /* input,  ptr to existing bitmap surface */
            MGBITMAP  *bitmap );     /* output, bitmap-handle                  */
     
    MGEXTERN                      /* create a bitmap object (advanced)         */
    MRESULT mgBitmap_Create(         /* return, completion code (0=success)    */
            MGBITMAPINFO *bitmapInfo,/* in/out, bitmap information structure   */
            MGBITMAP     *bitmap );  /* output, bitmap-handle                  */

Here is an example of how we define a bitmap for TypeServer use:

  
    MGBITMAP  myBitmap=NULL;    /* bitmap-handle           */
    
    /* define a bitmap instance */
    mgBitmap_CreateDirect( 1024, 768, 8, NULL, &myBitmap );
    if ( myBitmap == NULL )
        { /* handle error condition */ }

The above example defines a 256-color, 8 bit-per-pixel bitmap that is 1024 pixels wide and 768 pixels high. Since we passed a NULL pointer for the bitmap surface, the create function will dynamically allocate a new bitmap surface for us in local memory. To define an existing bitmap, pass the "surface" pointer with the starting address of the frame buffer in memory. When the function returns, the bitmap-handle will contain an identifier for the bitmap that can be used in calling other TypeServer funtions.

TypeServer Bitmap

next»