ufmGetTransformedBitmap(3w)

NAME
     ufmGetTransformedBitmap - get a transformed character bitmap

C SYNOPSIS
     #include <ufm.h>

     int ufmGetTransformedBitmap(unsigned int nTypefaceHandles,
          unsigned int *typefaceHandles, int charCodeType,
          unsigned int nCharCodes, void *charCodes, float transfMatrix[4],
          unsigned int *nCharBitmaps, ufmBitmap **charBitmaps)

DESCRIPTION
     ufmGetTransformedBitmap gets transformed bitmaps for specified
     characters. You can get a character bitmap only for those typefaces for
     which bitmap or outline font files were found, that is, those typefaces
     which have the bit ufmTypefaceBitmaps set to 1 in their data structures
     of the type ufmTypeface.

     nTypefaceHandles specifies the number of entries (typeface handles) in
     the array typefaceHandles.

     typefaceHandles specifies one or more handles for open typefaces.  Use
     the function ufmOpenTypeface to open a typeface, and get a handle for
     that typeface.

     If you specify more than one typeface handle, ufmGetTransformedBitmap
     will look for bitmap fonts of the size pixelSize in specified typefaces.
     If it does not find a requested bitmap font, it will create it.  Then it
     will look for the bitmap of a specified character in the bitmap font for
     the first specified typeface.  If it does not find it in that font, it
     will look for that bitmap in the next bitmap font.  It will stop looking
     as soon as it finds the requested character bitmap.  If it cannot find
     that bitmap, it will return the bitmap for the default character.  If
     ufmGetTransformedBitmap cannot find the bitmap even for the default
     character, it will return an error code.

     charCodeType specifies a 1-byte character code (UFM_BYTE1), a Unicode
     UCS-2 code (UFM_UCS2), a Unicode UCS-4 code (UFM_UCS4), a 2-byte
     character code (UFM_BYTE2), or a 4-byte character code (UFM_BYTE4).

     nCharCodes specifies the number of elements in the array charCodes.  Set
     nCharCodes to 0 if you want bitmaps for all characters in a specified
     typeface.  If you want bitmaps for only some characters, use the array
     charCodes to specify the character codes of those characters.

     transfMatrix specifies a 4-element transformation matrix that needs to be
     applied to character bitmaps. This is a column-major matrix. Specify
     matrix elements in the following sequence: 00, 10, 01 and 11.

     ufmGetTransformedBitmap returns the number of character bitmaps it finds
     (nCharBitmaps) and the address of the array in which it stores those
     character bitmaps (ufmBitmap).
     When you are finished with the array (ufmBitmap), you can free it by
     calling ufmFreeBitmap with the argument values that were returned by
     ufmGetTransformedBitmap.

     A bitmap image provided by the function ufmGetTransformedBitmap should be
     interpreted the same way as image data for the OpenGL function
     glDrawPixels, with width and height corresponding to the width and height
     arguments in that function, and with type set to GL_BITMAP and format set
     to GL_COLOR_INDEX.

     Each row of the bitmap is padded to a 4-byte boundary.  If you want to
     use the information provided by ufmGetTransformedBitmap to create OpenGL
     font display lists, that is, to call OpenGL functions glNewList,
     glBitmap, and glEndList, you should start by calling glPixelStore
     function with the arguments GL_UNPACK_ALIGNMENT and 4.  For example, if
     you decide to use the function glPixelStorei, you should specify
     glPixelStorei(GL_UNPACK_ALIGNMENT, 4).

SEE ALSO
     ufmFreeBitmap(3w) and ufmGetBitmap(3w).

DIAGNOSTICS
     If ufmGetTransformedBitmap is not able to allocate the memory it needs,
     it will return the value UFM_OUT_OF_MEMORY.  If the values of one or more
     arguments are not valid, ufmGetTransformedBitmap will return the value
     UFM_INVALID_VALUE.  UFM_OUT_OF_MEMORY and UFM_INVALID_VALUE are defined
     in the header file <ufm.h>.