Table of Contents

3. Bitmaps, Raster Fonts and Textures - Bitmap,RasFont,Texture

The Bitmap and RasFont modules are designed to support bitmap operations. Bitmap objects store bitmaps which are used for a variety of purposes in VglTools. A Bitmap bitmap may represent a line style or a polygon fill pattern for use with a ZBuffer object. It may also be used to represent a character of a raster text font for use with a RasFont object. RasFont objects store raster text fonts as many individual Bitmap objects and are used to define raster fonts to the graphics device interface.

The Texture module enables applications to define raster images and texturing parameters to be used to map image data onto graphics primitives. Texture objects differ from Bitmap objects in that a Bitmap object only stores a single bit at each pixel whereas a Texture object stores "image" data, which generally consists of 32 bits, at each pixel. Texture image data may be set pixel by pixel from the host application or loaded from industry standard image files via an FBuffer object. For applications in scientific visualization or finite element post processing, algorithmically generated, one-dimensional texture maps representing the mapping of scalar data to color are useful.

Table of Contents

3.1 Bitmap Creation and Manipulation - Bitmap

A Bitmap object is a bitmap (depth of one bit) of arbitrary width and height. Bitmap objects generally serve as attribute objects to ZBuffer objects to define line styles and polygon fill patterns and to RasFont objects as individual raster font character definitions. A user may define a Bitmap object from scratch or select from one of several built-in bitmaps. The functions associated with a Bitmap object are the following.

Table of Contents

3.2 Creation

A Bitmap object may be created in a straight-forward way for use as a line style or polygon fill pattern by using vgl_BitmapLoad. This function allows the user to select from one of several built-in bitmaps. The bitmap available for line styles are 1x16 bitmaps which implement various types of dotted, dashed and dot-dashed line styles. 

     BITMAP_DOT           xx      xx      xx      xx 
     BITMAP_DASH          xxxx    xxxx    xxxx    xxxx
     BITMAP_DOTDASH       xxxx    xx      xxxx    xx   
     BITMAP_LDASH         xxxxxx  xxxxxx  xxxxxx  xxxxxx
     BITMAP_DOTLDASH      xxxxxx    xx    xxxxxx    xx  
     BITMAP_DOTDOT        xx  xx  xx  xx  xx  xx  xx  xx
     BITMAP_DOTDOTLDASH   xxxxxx  xx  xx  xxxxxx  xx  xx
     BITMAP_LLDASH        xxxxxxxxxxxx    xxxxxxxxxxxx
For polygon fill, bitmaps are 16x16 arrays which have various amounts of bit density for implementing "screen door" type transparency. Figure 3-1 illustrates polygon transparency fill patterns which are available.


Figure 3-1, Polygon transparency fill patterns.
In addition there are several built-in bitmaps of utility in stippling polygons. Alternatively bitmaps may be built from scratch. The Bitmap module has functions for declaring the size of bitmaps, vgl_BitmapDef, and setting individual bits in the bitmap, vgl_BitmapSetBit and vgl_BitmapSetRast.

Table of Contents

3.3 Function Descriptions

The currently available Bitmap functions are described in detail in this section.

Table of Contents , Bitmap

NAME

*vgl_BitmapBegin - create an instance of an Bitmap object

C SPECIFICATION

vgl_Bitmap *vgl_BitmapBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Bitmap object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of an Bitmap object. Memory is allocated for the object private data and the pointer to the data is returned. By default the bitmap dimensions are zero.

Destroy an instance of a Bitmap object using 

     void vgl_BitmapEnd (vgl_Bitmap *bitmap)

Return the current value of a Bitmap object error flag using 

     Vint vgl_BitmapError (vgl_Bitmap *bitmap)

Make a copy of a Bitmap object. The private data from the frombitmap object is copied to the bitmap object. Any previous private data in bitmap is lost. 

     void vgl_BitmapCopy (vgl_Bitmap *bitmap,
                          vgl_Bitmap *frombitmap)

Table of Contents , Bitmap

NAME

vgl_BitmapClear - clear entire bitmap to zero

C SPECIFICATION

void vgl_BitmapClear (vgl_Bitmap *bitmap)

INPUT ARGUMENTS

bitmap       Pointer to Bitmap object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set all bits in bitmap memory to zero.

Table of Contents , Bitmap

NAME

vgl_BitmapDef - define bitmap dimensions

C SPECIFICATION

void vgl_BitmapDef (vgl_Bitmap *bitmap,
                    Vint width,
                    Vint height)

INPUT ARGUMENTS

bitmap       Pointer to Bitmap object.
width        Width of the bitmap in pixels
height       Height of the bitmap in pixels

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if an invalid width or height is specified. VGL_ERROR_MEMORY is generated if bitmap memory allocation fails.

DESCRIPTION

Define the dimensions of a bitmap. Any previous bitmap contents are lost. Bitmap memory is allocated at this time. This function may be called anytime to change bitmap dimensions. Bitmap width and height must be less than 256.

Inquire of defined width and height as output arguments using 

     void vgl_BitmapInq (vgl_Bitmap *bitmap,
                         Vint *width,
                         Vint *height)

Table of Contents , Bitmap

NAME

vgl_BitmapLoad - create one of several built-in bitmaps

C SPECIFICATION

void vgl_BitmapLoad (vgl_Bitmap *bitmap,
                     Vint irast)

INPUT ARGUMENTS

bitmap       Pointer to Bitmap object.
irast        The type of built-in bitmap to create
             =BITMAP_DOT             Dotted line style bitmap
             =BITMAP_DASH            Dashed line style bitmap
             =BITMAP_DOTDASH         Dot-dashed line style bitmap
             =BITMAP_SCREEN1         Pattern with 1/8 transparency
             =BITMAP_SCREEN2         Pattern with 2/8 transparency
             =BITMAP_SCREEN3         Pattern with 3/8 transparency
             =BITMAP_SCREEN4         Pattern with 4/8 transparency
             =BITMAP_SCREEN5         Pattern with 5/8 transparency
             =BITMAP_SCREEN6         Pattern with 6/8 transparency
             =BITMAP_SCREEN7         Pattern with 7/8 transparency
             =BITMAP_SCREEN8         Pattern with full transparency
             =BITMAP_XES5            Small Xs
             =BITMAP_XES7            Larger Xs
             =BITMAP_CIRCLES5        Small circles
             =BITMAP_CIRCLES7        Larger circles
             =BITMAP_DIAMONDS5       Small diamonds
             =BITMAP_DIAMONDS7       Larger diamonds
             =BITMAP_BOXES5          Small boxes
             =BITMAP_BOXES7          Larger boxes
             =BITMAP_SQUARE4         Small squares
             =BITMAP_SQUARE8         Larger sqares
             =BITMAP_SQUARE8B        Larger bold squares
             =BITMAP_SQUARE16B       Large bold squares
             =BITMAP_CROSS8          Larger crosses
             =BITMAP_CROSS8B         Larger bold crosses
             =BITMAP_CROSS16         Large crosses
             =BITMAP_CROSS16B        Large bold crosses
             =BITMAP_BDIAGONAL8      Large upward left-right diagonal
             =BITMAP_BDIAGONAL8B     Large bold upward left-right diagonal
             =BITMAP_BDIAGONAL16     Larger upward left-right diagonal
             =BITMAP_BDIAGONAL16B    Larger bold upward left-right diagonal
             =BITMAP_FDIAGONAL8      Large downward left-right diagonal
             =BITMAP_FDIAGONAL8B     Large bold downward left-right diagonal
             =BITMAP_FDIAGONAL16     Larger downward left-right diagonal
             =BITMAP_FDIAGONAL16B    Larger bold downward left-right diagonal
             =BITMAP_HORIZONTAL4     Small horizontal hatch
             =BITMAP_HORIZONTAL8     Large horizontal hatch
             =BITMAP_HORIZONTAL8B    Large bold horizontal hatch
             =BITMAP_HORIZONTAL16B   Larger bold horizontal hatch
             =BITMAP_VERTICAL4       Small vertical hatch
             =BITMAP_VERTICAL8       Large vertical hatch
             =BITMAP_VERTICAL8B      Large bold vertical hatch
             =BITMAP_VERTICAL16B     Larger bold vertical hatch
             =BITMAP_PLUS9           Point icon +
             =BITMAP_ASTERISK9       Point icon *
             =BITMAP_CROSS9          Point icon x
             =BITMAP_BOX9            Point icon box
             =BITMAP_CROSSBOX9       Point icon crossed box
             =BITMAP_CIRCLE9         Point icon circle
             =BITMAP_TRIUP9          Point icon upward pointing triangle
             =BITMAP_TRIRIGHT9       Point icon right pointing triangle
             =BITMAP_TRIDOWN9        Point icon downward pointing triangle
             =BITMAP_TRILEFT9        Point icon left pointing triangle
             =BITMAP_DIAMOND9        Point icon diamond
             =BITMAP_TBOXBITS        Point icon box with bits
             =BITMAP_TDIAMONDBITS    Point icon diamond with bits
             =BITMAP_CROSSCIRCLE9    Point icon crossed circle
             =BITMAP_PLUSCIRCLE9     Point icon plussed circle

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper irast is specified. VGL_ERROR_MEMORY is generated if bitmap memory allocation fails.

DESCRIPTION

Load a bitmap from a built-in bitmap definition. All bitmap query operations may be used on the resulting bitmap. Note that the BITMAP_SCREEN8 bitmap has no bits set.

The following bitmaps are identical to Microsoft Windows brush patterns. 

Bitmap irast           Microsoft hatch brush pattern index
BITMAP_HORIZONTAL8     HS_HORIZONTAL
BITMAP_VERTICAL8       HS_VERTICAL
BITMAP_SQUARE8         HS_CROSS
BITMAP_CROSS8          HS_DIAGCROSS
BITMAP_BDIAGONAL8      HS_BDIAGONAL
BITMAP_FDIAGONAL8      HS_FDIAGONAL

The "Point icon" bitmaps are specifically designed to be used as bitmaps for point drawing. All symbols are unfilled.

This function frees any existing bitmap before loading the specified built-in bitmap. The bitmap dimensions of irast are set, memory is allocated and the specified bitmap is loaded.

Table of Contents , Bitmap

NAME

vgl_BitmapSetBit - set an individual bit value in a bitmap

C SPECIFICATION

void vgl_BitmapSetBit (vgl_Bitmap *bitmap,
                       Vint ix, Vint iy,
                       Vint bit)

INPUT ARGUMENTS

bitmap       Pointer to Bitmap object.
ix, iy       Coordinates of bit
bit          Bit value to set

OUTPUT ARGUMENTS

None

DESCRIPTION

Set a single bit value into a bitmap in a specified location. Bitmap coordinates start from 0,0 at the lower left hand corner.

Get bit as an output argument using 

     void vgl_BitmapGetBit (vgl_Bitmap *bitmap,
                            Vint ix, Vint iy,
                            Vint *bit)

Table of Contents , Bitmap

NAME

vgl_BitmapSetRast - set bitmap from array

C SPECIFICATION

void vgl_BitmapSetRast (vgl_Bitmap *bitmap,
                        Vuchar *rast)

INPUT ARGUMENTS

bitmap       Pointer to Bitmap object.
rast         Array of bits to copy to bitmap memory

OUTPUT ARGUMENTS

None

DESCRIPTION

Copy a bitmap from an array to bitmap memory. Characters are copied from rast until a enough bits have been copied to fill the bitmap.

Copy a bitmap from bitmap memory to array rast using 

     void vgl_BitmapGetRast (vgl_Bitmap *bitmap,
                             Vuchar *rast)

Table of Contents

3.4 Raster Fonts - RasFont

The RasFont module is designed specifically to store raster text fonts. A RasFont object stores a font as many individual Bitmap objects. Generally a RasFont object is created using one of the built-in fonts, a FreeType font or by loading a font supported by the window system. However a user may define a font from scratch or modify a built-in font. The functions associated with a RasFont object are the following.

Table of Contents

3.5 Creation and Attributes

A RasFont object may be created with a built-in font using vgl_RasFontLoad or a X windows font using vgl_RasFontLoadXFont. Microsoft Windows fonts may be loaded using vgl_RasFontLoadWINFont. These options are the most convenient way to create a font. Since a raster font is composed of an individual bitmap object for each character, it is possible to get the bitmap object for a character and alter it using Bitmap module functions. This is true even for built-in or window system fonts. If one uses a built-in or window system font it is not necessary to set the height, width, base and offset of the font using vgl_RasFontSetMetrics. this is done automatically by vgl_RasFontLoad, vgl_RasFontLoadXFont or vgl_RasFontLoadWINFont. The size and spacing of any font may be changed by calling vgl_RasFontSetSize and vgl_RasFontSetSpacing. The user may construct a font character by character by building a Bitmap object for each character and setting it by calling vgl_RasFontSetBitmap. In this case vgl_RasFontSetMetrics must be called to set the overall font metrics and vgl_RasFontSetCharWidth must be called if the font is proportionately spaced.

Note that the font size is limited by the maximum size allowed by Bitmap. This size limit is currently 256 by 256.

Figure 3-2 illustrates the available built-in fonts.


Figure 3-2, Built-in Raster Fonts
A maximum width, height, offset and base are used to characterize a font. A character width may be specified for each character in the font. This means that RasFont supports both constant width and proportionately spaced fonts. The character width and height are the number of pixels written horizontally and vertically for each character starting from the lower left hand corner of the bitmap defining each character. The character width and height must be less than or equal to the bitmap width and height. The character origin is the location in the character bitmap which will be put at the specified character device coordinate when the character is drawn. The x and y coordinates of the character origin in a bitmap are specified by the offset and base respectively. Typically a character font with descenders will have a positive character base to account for the number of bitmap rows required for the character descenders.

Table of Contents

3.6 Using FreeType Fonts

The RasFont module may be used to load FreeType fonts. The RasFont module must be compiled with VKI_LIBAPI_FREETYPE defined. Use vgl_RasFontFreeTypeParam to query for the number of fixed point and/or scaleable fonts available in a FreeType supported font file. A FreeType font file may contain one or both types of fonts. Use vgl_RasFontFixedFreeType to query for the sizes of fixed point fonts. Use vgl_RasFontLoadFixedFreeType to load a specified fixed point font size. Use vgl_RasFontLoadFreeType to load a specified size of a scaleable font.

Table of Contents

3.7 Using RasFont in Drawing Functions

The RasFont module may be used to specify raster fonts in any graphics interface module. A RasFont object which encapsulates the complete description of a raster font is passed to the graphics interface using vgl_DrawFunRasFontDefine. Any number of raster fonts may be defined in this way, each assigned to a positive raster font index. When the RasFont object is passed to the graphics interface using vgl_DrawFunRasFontDefine, the graphics interface makes a copy of the defined RasFont object. Once defined, the current raster font is selected by index using vgl_DrawFunRasFontSelect. The current raster font is used for all subsequent Text and TextDC operations. Selecting an index of 0 enables the default raster font. This methodology is similar to that used for defining and selecting textures using the Texture module.

By default a raster font is drawn anchored at a world coordinate location and directed to the right in a plane perpendicular to the view direction, only the anchor point location is affected by modelview and projection transformations. However, as an option, raster fonts may be drawn in a user defined direction and plane. This option is enabled using vgl_RasFontSetParami with the parameter RASFONT_TEXTPLANE enabled. A raster font with RASFONT_TEXTPLANE enabled which is passed to the graphics interface using vgl_DrawFunRasFontDefine will be drawn using the current text plane. The drawing function vgl_DrawFunTextPlane is used to set the current text plane. An option is provided to control the scaling of the orientable raster font. Use vgl_RasFontSetParami with parameter RASFONT_DEVICESIZE to toggle device scaling of the raster font. If device scaling is enabled then the size of a pixel in the raster font bitmap will be approximately the size of a pixel on the graphics device. If device scaling is disabled then the size of a pixel in the raster font bitmap will be the raster font pixelsize specified using vgl_RasFontSetPixelSize.

Table of Contents

3.8 Function Descriptions

The currently available RasFont functions are described in detail in this section.

Table of Contents , RasFont

NAME

*vgl_RasFontBegin - create an instance of a RasFont object

C SPECIFICATION

vgl_RasFont *vgl_RasFontBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created RasFont object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a RasFont object. Memory is allocated for the object private data and the pointer to the data is returned. By default all font metrics and spacing attributes are zero, the font size multiplier is unity. Note that vgl_RasFontEnd destroys all Bitmap objects which have been used to define the raster font. This means that vgl_BitmapEnd is called internally for all Bitmap objects.

Destroy an instance of a RasFont object using 

     void vgl_RasFontEnd (vgl_RasFont *rasfont)

Return the current value of a RasFont object error flag using 

     Vint vgl_RasFontError (vgl_RasFont *rasfont)

Make a copy of a RasFont object. The private data from the fromrasfont object is copied to the rasfont object. Any previous private data in rasfont is lost. 

     void vgl_RasFontCopy (vgl_RasFont *rasfont,
                           vgl_RasFont *fromrasfont)

Table of Contents , RasFont

NAME

vgl_RasFontDraw - draw a raster font

C SPECIFICATION

void vgl_RasFontDraw (vgl_RasFont *rasfont,
                      Vfloat x[3],
                      Vint dc[3],
                      Vtchar *text)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
x            World coordinate anchor point
dc           Device coordinate offset
text         Text string

OUTPUT ARGUMENTS

None

DESCRIPTION

Draw a text string with a device coordinate offset, dc anchored at world coordinate location x. The use of this function requires that a DrawFun attribute object has been installed using vgl_RasFontSetObject. The drawing functions AttPush, AttPop, PointSize and PolyPointDC are required.

Table of Contents , RasFont

NAME

vgl_RasFontLength - query length of a text string

C SPECIFICATION

void vgl_RasFontLength (vgl_RasFont *rasfont,
                        Vtchar *text,
                        Vint *length)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
text         Text string

OUTPUT ARGUMENTS

length       Length of text string in pixels

DESCRIPTION

Compute and return the length of a given text string in pixels. The text string is not drawn.

Table of Contents , RasFont

NAME

vgl_RasFontLoad - load one of several built-in raster fonts

C SPECIFICATION

void vgl_RasFontLoad (vgl_RasFont *rasfont,
                      Vint ifont)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
ifont        The type of built-in raster font to create
             =RASFONT_QUALITY9X13    Create 9x13 font
             =RASFONT_NORMALBOLD8X14 Create 8x14 font
             =RASFONT_NORMAL7X11     Create 7x11 font

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper ifont is specified.

DESCRIPTION

Load a raster font from a built-in font definition. All raster font operations may be used on the resulting raster font. Any Bitmap objects used to define a previously loaded raster font are destroyed. Currently all built-in fonts are constant width. Font metrics are set by this function. Character spacing and size may be specified by the user.

Table of Contents , RasFont

NAME

vgl_RasFontFreeTypeParam - query FreeType parameters

C SPECIFICATION

void vgl_RasFontFreeTypeParam (vgl_RasFont *rasfont,
                               Vchar *fontname,
                               Vint itype,
                               Vint *iparam)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
fontname     Specifies the FreeType font file name.
itype        The FreeType fonts available
             =RASFONT_FREETYPE_NUMFIXED Number of fixed point fonts
             =RASFONT_FREETYPE_SCALABLE Scaleable font available

OUTPUT ARGUMENTS

iparam       Parameter value

ERRORS

VGL_ERROR_FILE is generated if an improper fontname is specified. VGL_ERROR_ENUM is generated if an improper itype is specified.

DESCRIPTION

Given a FreeType font file return either the number of fixed point fonts available or a flag indicating that a scaleable font is available.

Table of Contents , RasFont

NAME

vgl_RasFontFixedFreeType - query FreeType fixed point sizes

C SPECIFICATION

void vgl_RasFontFreeTypeParam (vgl_RasFont *rasfont,
                               Vchar *fontname,
                               Vint (*fixed)[2])

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
fontname     Specifies the FreeType font file name.

OUTPUT ARGUMENTS

fixed        Available Fixed point widths and heights.

ERRORS

VGL_ERROR_FILE is generated if an improper fontname is specified.

DESCRIPTION

Given a FreeType font file return the widths and heights of all fixed point fonts. Use vgl_RasFontFreeTypeParam to return the number of fixed point font sizes, numsize. The size of the fixed array should be 2*numsize integers. The fixed[i][0] and fixed[i][1] are the width and height of the ith fixed point size.

Table of Contents , RasFont

NAME

vgl_RasFontLoadFreeType - load a scaleable FreeType font

C SPECIFICATION

vgl_RasFontLoadFreeType (vgl_RasFont *rasfont,
                         Vint height,
                         Vchar *fontname)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
height       Point height of scaleable font
fontname     Specifies the FreeType font file name.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_FILE is generated if an improper fontname is specified.

DESCRIPTION

Given a FreeType font file load a scaleable font with size height.

Table of Contents , RasFont

NAME

vgl_RasFontLoadFixedFreeType - load a fixed point FreeType font

C SPECIFICATION

vgl_RasFontLoadFixedFreeType (vgl_RasFont *rasfont,
                              Vint height,
                              Vchar *fontname)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
height       Point height of fixed point font
fontname     Specifies the FreeType font file name.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_FILE is generated if an improper fontname is specified.

DESCRIPTION

Given a FreeType font file load a fixed point font with size height.

Table of Contents , RasFont

NAME

vgl_RasFontLoadWINFont - load a Microsoft Windows font

C SPECIFICATION

void vgl_RasFontLoadWINFont (vgl_RasFont *rasfont,
                             HFONT hfont)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
hfont        Specifies a handle to a Microsoft Windows font

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if an invalid hfont is specified.

DESCRIPTION

Load a Microsoft windows font. The font may be a raster, vector or TrueType font created with Win32 API functions such as CreateFont, CreateFontIndirect or GetStockObject. When the font is loaded, it is rasterized with the current characteristics of the logical font, hfont. All raster font operations may be used on the resulting raster font. Any Bitmap objects used to define a previously loaded raster font are destroyed. Constant and proportionate width fonts are supported. Font metrics are set by this function. Character spacing and size may be specified by the user.

Table of Contents , RasFont

NAME

vgl_RasFontLoadXFont - load a X windows font

C SPECIFICATION

void vgl_RasFontLoadXFont (vgl_RasFont *rasfont,
                           Display *display,
                           Vchar *fontname)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
display      Specifies a Display connection to the X server
fontname     Specifies the name of the font.  The font name is a null
             terminated string which conforms to the X windows font
             naming convention.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_FILE is generated if an improper fontname is specified.

DESCRIPTION

Load a raster font from a X windows. All raster font operations may be used on the resulting raster font. Any Bitmap objects used to define a previously loaded raster font are destroyed. Constant and proportionate width fonts are supported. Font metrics are set by this function. Character spacing and size may be specified by the user.

Table of Contents , RasFont

NAME

vgl_RasFontSetBitmap - set pointer to bitmap object for a character

C SPECIFICATION

void vgl_RasFontSetBitmap (vgl_RasFont *rasfont,
                           Vint ichar,
                           vgl_Bitmap *bitmap)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
ichar        Character position in rasfont to install bitmap
bitmap       Pointer to Bitmap object defining character

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if an ichar out of range is specified.

DESCRIPTION

Set a pointer to the bitmap object defining a character into a character position in a raster font. The character position is the character's ASCII value. For example the ASCII value of A is 65 (decimal) so character position 65 should be used to store the bitmap for A. Note that the RasFont object now "owns" the set Bitmap. Any previously set Bitmap will be deleted. All set Bitmap objects will be deleted when the RasFont object is deleted.

Get bitmap as an output argument using 

     void vgl_RasFontGetBitmap (vgl_RasFont *rasfont,
                                Vint ichar,
                                vgl_Bitmap **bitmap)

Table of Contents , RasFont

NAME

vgl_RasFontSetCharWidth - set character width

C SPECIFICATION

void vgl_RasFontSetCharWidth (vgl_RasFont *rasfont,
                              Vint ichar,
                              Vint width)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
ichar        Character position in rasfont to set character width
width        Character width

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if an ichar out of range is specified.

DESCRIPTION

Set the width of a character. Use this function to set the individual character widths in a raster font if proportionate spacing is required. If the character width is not set by this function, then the character width set by the vgl_RasFontSetMetrics function is used.

Get width as an output argument using 

     void vgl_RasFontGetCharWidth (vgl_RasFont *rasfont,
                                   Vint ichar,
                                   Vint *width)

Table of Contents , RasFont

NAME

vgl_RasFontSetClampSize - set font size minmax limits

C SPECIFICATION

void vgl_RasFontSetClampSize (vgl_RasFont *rasfont,
                              Vfloat minsize,
                              Vfloat maxsize)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
minsize      Bitmap pixel size

OUTPUT ARGUMENTS

None

DESCRIPTION

Set device size limits to the projected size of a bitmap pixel. The specified minimum and maximum sizes are used to clamp the projected size of a bitmap pixel when world coordinate sizing is in effect. An orientable raster font with world coordinate sizing and size clamping is specified using vgl_RasFontSetParami with RASFONT_TEXTPLANE enabled, RASFONT_DEVICESIZE disabled and RASFONT_CLAMPSIZE enabled. The default minsize is .5 and maxsize is 2.

Table of Contents , RasFont

NAME

vgl_RasFontSetMetrics - set width, height, offset and base of font

C SPECIFICATION

void vgl_RasFontSetMetrics (vgl_RasFont *rasfont,
                            Vint width, Vint height,
                            Vint offset, Vint base)

INPUT ARGUMENTS

rasfont        Pointer to RasFont object.
width, height  Width and height of character in pixels.
offset, base   Horizontal and vertical position of character origin in
               raster.

OUTPUT ARGUMENTS

None

DESCRIPTION

Set maximum width, height, offset and base of font characters. All characters of a raster font share the same height, offset and base, the character width may vary for each character, width represents the maximum character width.

Get width, height, offset and base as output arguments using 

     void vgl_RasFontGetMetrics (vgl_RasFont *rasfont,
                                 Vint *width, Vint *height,
                                 Vint *offset, Vint *base)

Table of Contents , RasFont

NAME

vgl_RasFontSetObject - set pointers to attribute objects

C SPECIFICATION

void vgl_RasFontSetObject (vgl_RasFont *rasfont,
                           Vint objecttype,
                           Vobject *object)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
objecttype   The name of the object type to be set.
             =VGL_DRAWFUN            DrawFun object
object       Pointer to the object to be set.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_OBJECTTYPE is generated if an improper objecttype is specified.

DESCRIPTION

Set a pointer to an attribute object. The DrawFun attribute object is required for drawing raster fonts with vgl_RasFontDraw.

Table of Contents , RasFont

NAME

vgl_RasFontSetParami - set raster font parameters

C SPECIFICATION

void vgl_RasFontSetParami (vgl_RasFont *rasfont,
                           Vint type,
                           Vint iparam)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
type         Type of display parameter to set
             =RASFONT_ANTIALIAS        Toggle antialiased font support
             =RASFONT_DIRECTION        Set raster font direction
             =RASFONT_TEXTPLANE        Toggle orientable raster font
             =RASFONT_DEVICESIZE       Toggle raster font device sizing
             =RASFONT_CLAMPSIZE        Toggle raster font size clamping
iparam       Specifies the integer value that type will be set to.
             =SYS_ON                   Enable
             =SYS_OFF                  Disable

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Enable support for quality rendering of antialised fonts using RASFONT_ANTIALIAS By default RASFONT_ANTIALIAS is set to SYS_OFF.

Enable orientable raster font using RASFONT_TEXTPLANE. By default RASFONT_TEXTPLANE is set to SYS_OFF.

Enable device sizing of an orientable raster font using RASFONT_DEVICESIZE. If device sizing is disabled, then the size of a pixel in the raster font bitmap is scaled to the world coordinate size specified by vgl_RasFontSetPixelSize. If device sizing is enabled then the size of a pixel in the raster font bitmap will be scaled to the size of a pixel on the graphics screen. By default RASFONT_DEVICESIZE is set to SYS_ON.

Enable size clamping of an orientable raster font when device sizing, RASFONT_DEVICESIZE, is disabled. In this case the projected size of a bitmap pixel is clamped to the device sizes specified by vgl_RasFontSetClampSize. This allows some device size control of a raster font which is world coordinate scaled. By default RASFONT_CLAMPSIZE is set to SYS_OFF.

Set the direction of a raster font using RASFONT_DIRECTION. The direction may be VGL_RIGHT, VGL_LEFT, VGL_BOTTOM or VGL_TOP. This option only applies to a non-orientable raster font. By default RASFONT_DIRECTION is set to VGL_RIGHT.

Table of Contents , RasFont

NAME

vgl_RasFontSetPixelSize - set raster font pixelsize

C SPECIFICATION

void vgl_RasFontSetPixelSize (vgl_RasFont *rasfont,
                              Vfloat pixelsize)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
pixelsize    Bitmap pixel size

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the world coordinate pixel size. The specified pixel size is used to determine the world coordinate size of a bitmap pixel in an orientable raster font. An orientable raster font with world coordinate sizing is specified using vgl_RasFontSetParami with RASFONT_TEXTPLANE enabled and RASFONT_DEVICESIZE disabled. The default pixel size is 1.

Table of Contents , RasFont

NAME

vgl_RasFontSetSize - set character size multiplier

C SPECIFICATION

void vgl_RasFontSetSize (vgl_RasFont *rasfont,
                         Vint size)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
size         Character size multiplier

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the character size multiplier. Any font may be magnified by a positive integer multiplier. The magnification factor affects all character metrics and spacing. Any size less than 1 is set to 1. The default size is 1.

Get size as an output argument using 

     void vgl_RasFontGetSize (vgl_RasFont *rasfont,
                              Vint *size)

Table of Contents , RasFont

NAME

vgl_RasFontSetSpacing - set character spacing

C SPECIFICATION

void vgl_RasFontSetSpacing (vgl_RasFont *rasfont,
                            Vint spacing)

INPUT ARGUMENTS

rasfont      Pointer to RasFont object.
spacing      Number of pixels to insert between characters

OUTPUT ARGUMENTS

None

DESCRIPTION

Set the number of pixels to insert between characters in a text string. Any spacing less than zero is set to zero. The default spacing is zero.

Get spacing as an output argument using 

     void vgl_RasFontGetSpacing (vgl_RasFont *rasfont,
                                 Vint *spacing)

Table of Contents

3.9 Texture Maps - Texture

The Texture module is designed to store textures. A texture consists of basic image data and associated texture parameters which specify filtering, boundary conditions, and blending and modulation to be applied when mapping the texture onto a graphics primitive. Textures, like images, may consist of one or two dimensional data. The individual values in a texture array are called texels. Texels may contain one to four elements (or channels) of data representing anything from a modulation constant to a RBBA quadruple.

The Texture module provides functions to set the texture data texel by texel or load it from industry standard image file formats. Texture parameters affecting filtering, modulation and blending and boundary conditions may be set. The functions associated with a Texture object are the following.

Table of Contents

3.10 Creation and Attributes

Instance a new Texture object using vgl_TextureBegin. Once instanced, texture parameters controlling boundary conditions, filtering, and modulation and blending may be set by calling vgl_TextureSetWrap, vgl_TextureSetFilter and vgl_TextureSetEnv respectively. By default the texture parameters are set to clamp the boundary values, perform "nearest" texel filtering and provide for a modulation mode environment. These defaults are set particularly for the application of using one dimensional textures to perform scalar field color mapping in scientific and engineering data visualization. Such applications include finite element post processing.

An individual texel may contain from one to four 8-bit components. These components are normally interpreted as red, green, blue and alpha values. The number of components per texel and the width and height of a texel array are specified using vgl_TextureDef. This function must be called if loading the texel data explicitly with vgl_TextureSetTexels or vgl_TextureSetColors. If one uses a built-in texture or imports a texture using vgl_TextureLoad or vgl_TextureFBuffer, the the depth and size of the texel information is set automatically. Any previous texel data is deleted and vgl_TextureDef is called internally with the appropriate sizes. These sizes may be queried using vgl_TextureInq.

Table of Contents

3.11 Using Texture in Drawing Functions

A Texture object which encapsulates the complete description of a texture and how it is to be mapped is passed to the graphics interface using vgl_DrawFunTextureDefine. Any number of textures may be defined in this way, each assigned to a positive texture index. When the Texture object is passed to the graphics interface using vgl_DrawFunTextureDefine, the graphics interface makes a copy of the defined Texture object. Once defined, the current texture is selected by index using vgl_DrawFunTextureSelect. The current texture is used for all subsequent Polygon, PolygonColor and PolygonData operations. Selecting an index of 0 disables texture mapping. This methodology is similar to that used for defining and selecting raster fonts using the RasFont module.

Table of Contents

3.12 Function Descriptions

The currently available Texture functions are described in detail in this section.

Table of Contents , Texture

NAME

*vgl_TextureBegin - create an instance of a Texture object

C SPECIFICATION

vgl_Texture *vgl_TextureBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created Texture object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a Texture object. Memory is allocated for the object private data and the pointer to the data is returned. By default all boundary conditions are set to wrap, filtering is set to nearest and the environment is set to modulation mode.

Destroy an instance of a Texture object using 

     void vgl_TextureEnd (vgl_Texture *texture)

Return the current value of a Texture object error flag using 

     Vint vgl_TextureError (vgl_Texture *texture)

Make a copy of a Texture object. The private data from the fromtexture object is copied to the texture object. Any previous private data in texture is lost. 

     void vgl_TextureCopy (vgl_Texture *texture,
                           vgl_Texture *fromtexture)

Table of Contents , Texture

NAME

vgl_TextureDef - define the size of texel data

C SPECIFICATION

void vgl_TextureDef (vgl_Texture *texture,
                     Vint components,
                     Vint xsize,
                     Vint ysize)

INPUT ARGUMENTS

texture      Pointer to Texture object.
components   Number of color components in texture.
             1 <= components <= 4.
xsize        Width of texture.
ysize        Height of texture.  Set ysize = 1 for one dimensional
             textures.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if components is specified out of range or xsize or ysize are improper values. VGL_ERROR_MEMORY is generated if texture memory was unable to be allocated.

DESCRIPTION

Define the number of components per texel and the width and height of the texture data. Any previously defined texture data is deleted. This function must be called before setting texture data explicitly using vgl_TextureSetTexels or vgl_TextureSetColors. This function is called internally when loading texture data using vgl_TextureLoad or vgl_TextureFBuffer. The texture data xsize and ysize values should be constrained to powers of 2. If the xsize and/or ysize values are not powers of 2, then the largest dimensions which are powers of 2 are used for the texture. The input image is simply truncated at these dimensions.

If components = 1, the texel data is assumed to be a single luminance value. If components = 2, the texel data is assumed to be a luminance/alpha pair. If components = 3, the texel data is assumed to be a red, green, blue triple. If components = 4, the texel data is assumed to be a red, green, blue and alpha quadruple.

Table of Contents , Texture

NAME

vgl_TextureFBuffer - load texture data from a FBuffer object

C SPECIFICATION

void vgl_TextureFBuffer (vgl_Texture *texture,
                         vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

texture      Pointer to Texture object.
fbuffer      Pointer to FBuffer object containing image data to load.

OUTPUT ARGUMENTS

None

DESCRIPTION

Load a texture from a FBuffer object. Texture data loaded from a FBuffer object is assumed to be a 4 component texture which is the width and height of the image data in the FBuffer object. The FBuffer module supports the importation of image data from many industry standard image file formats. This provides a mechanism for loading texture data from external files.

vgl_TextureDef is called internally with the appropriate number of texel components and data sizes.

Table of Contents , Texture

NAME

vgl_TextureLoad - load a built-in texture

C SPECIFICATION

void vgl_TextureLoad (vgl_Texture *texture,
                      Vint itext)

INPUT ARGUMENTS

texture      Pointer to Texture object.
itext        The type of built-in texture to create
             =TEXTURE_HUE_BANDED     Create a 3 component,
                                     256 by 1 texture containing
                                     a banded variation of hues from
                                     magenta through red.

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper itext is specified.

DESCRIPTION

Load a texture from a built-in texture definition. The function vgl_TextureDef is called internally with the appropriate number of texel components and data sizes.

Table of Contents , Texture

NAME

vgl_TextureSetColor - set texel as floating point color components

C SPECIFICATION

void vgl_TextureSetColor (vgl_Texture *texture,
                          Vint ix, Vint iy,
                          Vfloat c[])

INPUT ARGUMENTS

texture      Pointer to Texture object.
ix, iy       Device coordinates of texel to set.
c            Vector of floating point color components

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_VALUE is generated if improper ix or iy are specified.

DESCRIPTION

Set texel as floating point color components. All components are normalized in the interval [0.,1.]. The number of color components in c must be equal to components defined using vgl_TextureDef. Device coordinates range from (0,0) to (xsize-1,ysize-1) where xsize and ysize are the width and height of the texture in texels.

Get c as an output argument using 

     void vgl_TextureGetColor (vgl_Texture *texture,
                               Vint ix, Vint iy,
                               Vfloat c[])

Table of Contents , Texture

NAME

vgl_TextureSetColors - set texture data as floating point color components

C SPECIFICATION

void vgl_TextureSetColors (vgl_Texture *texture,
                           Vfloat c[])

INPUT ARGUMENTS

texture      Pointer to Texture object.
c            Vector of floating point color components

OUTPUT ARGUMENTS

None

DESCRIPTION

Set texture data as floating point color components. All components are normalized in the interval [0.,1.]. The number of color components in c must be equal to components times xsize times ysize defined using vgl_TextureDef.

Get c as an output argument using 

     void vgl_TextureGetColors (vgl_Texture *texture,
                                Vfloat c[])

Table of Contents , Texture

NAME

vgl_TextureSetEnv - set texture mapping environment

C SPECIFICATION

void vgl_TextureSetEnv (vgl_Texture *texture,
                        Vint env)

INPUT ARGUMENTS

texture      Pointer to Texture object.
env          Texture environment mode.
             =TEXTURE_BLEND          Blending mode
             =TEXTURE_DECAL          Decal mode
             =TEXTURE_MODULATE       Modulation mode

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper env is specified.

DESCRIPTION

The texture environment determines how an incoming color is modified by the texture data to produce an outgoing color which is written to the frame buffer. If texture mapping is disabled the outgoing color equals the incoming color. The following table summarizes the texturing operations for each environment mode depending upon the number of components in a texel where l is luminance, c is an RGB color triple and a is the associated alpha value in a texel. 

components   TEXTURE_MODULATE   TEXTURE_DECAL       TEXTURE_BLEND 

  1          cout=l*cin         undefined           cout=(1-l)*cin+l*cenv
             aout=ain                               aout=ain

  2          cout=l*cin         undefined           cout=(1-l)*cin+l*cenv
             aout=a*ain                             aout=a*ain

  3          cout=c*cin         cout=c              undefined
             aout=ain           aout=ain

  4          cout=c*cin         cout=(1-a)*cin+a*c  undefined
             aout=a*ain         aout=ain
The default is modulation mode. Use vgl_TextureSetEnvColor to set the environment color cenv.

Get env as an output argument using 

     void vgl_TextureGetEnv (vgl_Texture *texture,
                             Vint *env)

Table of Contents , Texture

NAME

vgl_TextureSetEnvColor - set environment color

C SPECIFICATION

void vgl_TextureSetEnvColor (vgl_Texture *texture,
                             Vfloat cenv[4])

INPUT ARGUMENTS

texture      Pointer to Texture object.
cenv         RGBA quadruple of environment color.

OUTPUT ARGUMENTS

None

DESCRIPTION

Specify the texture environment color used in blending mode operations, see vgl_TextureSetEnv. Note that four color components of cenv are required, red, green, blue and alpha. The components are normalized in the interval [0.,1.]. Be default the texture environment color is (0.,0.,0.,0.).

Get cenv as an output argument using 

     void vgl_TextureGetEnvColor (vgl_Texture *texture,
                                  Vfloat cenv[4])

Table of Contents , Texture

NAME

vgl_TextureSetFilter - set minification and magnification filters

C SPECIFICATION

void vgl_TextureSetFilter (vgl_Texture *texture,
                           Vint minfilter,
                           Vint magfilter)

INPUT ARGUMENTS

texture      Pointer to Texture object.
minfilter    Minification filter
             =TEXTURE_NEAREST        Use nearest filtering
             =TEXTURE_LINEAR         Use linear interpolation filtering
magfilter    Magnification filter
             =TEXTURE_NEAREST        Use nearest filtering
             =TEXTURE_LINEAR         Use linear interpolation filtering

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper minfilter or magfilter are specified.

DESCRIPTION

The texture filters determine the function used whenever the pixel being textured maps to an area greater than or less than one texture element. The minfilter is used when the pixel maps to an area greater than one texture element, the magfilter is used when the pixel maps to an area less than or equal to one texture element. Two filtering types are provided for each case, nearest filtering and linear filtering. Nearest filtering returns the value of the texture element that is nearest to the center fo the pixel being textured. This is generally the most computationally efficient method. Linear filtering returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. The default is TEXTURE_NEAREST for both minification and magnification filters.

Get minfilter and magfilter as output arguments using 

     void vgl_TextureGetFilter (vgl_Texture *texture,
                                Vint *minfilter,
                                Vint *magfilter)

Table of Contents , Texture

NAME

vgl_TextureSetTexels - set texel data as 32 bit unsigned integers

C SPECIFICATION

void vgl_TextureSetTexels (vgl_Texture *texture,
                           Vuint texels[])

INPUT ARGUMENTS

texture      Pointer to Texture object.
texels       Vector of RGBA data.

OUTPUT ARGUMENTS

None

DESCRIPTION

The red, green, blue and alpha components of the texture are returned as a vector of unsigned integers. The components are each packed into a byte of an unsigned integer for each texel. The total number of unsigned integers in texels should equal the number of texels in the texture. The red component is stored in the low byte, green in the middle low byte, red in the middle high byte and alpha in the high byte.

Get texels as an output argument using 

     void vgl_TextureGetTexels (vgl_Texture *texture,
                                Vuint texels[])

Table of Contents , Texture

NAME

vgl_TextureSetWrap - set texture boundary conditions

C SPECIFICATION

void vgl_TextureSetWrap (vgl_Texture *texture,
                         Vint swrap,
                         Vint twrap)

INPUT ARGUMENTS

texture      Pointer to Texture object.
swrap        Boundary condition for texture coordinate s.
             =TEXTURE_CLAMP          Clamp texture coordinate
             =TEXTURE_REPEAT         Repeat texture coordinate
twrap        Boundary condition for texture coordinate t.
             =TEXTURE_CLAMP          Clamp texture coordinate
             =TEXTURE_REPEAT         Repeat texture coordinate

OUTPUT ARGUMENTS

None

ERRORS

VGL_ERROR_ENUM is generated if an improper swrap or twrap are specified.

DESCRIPTION

The texture wrapping determines how the texture coordinates s and t are to be treated when they fall outside of the interval [0.,1.]. TEXTURE_CLAMP clamps the texture coordinate to the interval, while TEXTURE_REPEAT only uses the fractional part of the texture coordinate outside of the interval. The default is TEXTURE_CLAMP for both s and t boundary conditions.

Get swrap and twrap as an output arguments using 

     void vgl_TextureGetWrap (vgl_Texture *texture,
                              Vint *swrap,
                              Vint *twrap)