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.
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.
-
Begin and end an instance of an object, return object error flag
*vgl_BitmapBegin - create an instance of a Bitmap object vgl_BitmapEnd - destroy an instance of a Bitmap object vgl_BitmapError - return Bitmap object error flag vgl_BitmapCopy - make a copy of a Bitmap object -
Manipulate bitmap
vgl_BitmapClear - clear all bitmap bits to zero vgl_BitmapDef - define bitmap dimensions Inq - inquire bitmap dimensions vgl_BitmapLoad - create one of several built-in bitmaps vgl_BitmapSetBit - set individual bit value GetBit - get individual bit value vgl_BitmapSetRast - copy bitmap from array GetRast - copy bitmap to array
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.3.3 Function Descriptions
The currently available Bitmap functions are described in detail in this section.Bitmap
NAME
*vgl_BitmapBegin - create an instance of an Bitmap objectC 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)
Bitmap
NAME
vgl_BitmapClear - clear entire bitmap to zeroC 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.Bitmap
NAME
vgl_BitmapDef - define bitmap dimensionsC 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)
Bitmap
NAME
vgl_BitmapLoad - create one of several built-in bitmapsC 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.
Bitmap
NAME
vgl_BitmapSetBit - set an individual bit value in a bitmapC 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)
Bitmap
NAME
vgl_BitmapSetRast - set bitmap from arrayC 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)
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.
-
Begin and end an instance of an object, return object error flag
*vgl_RasFontBegin - create an instance of a RasFont object vgl_RasFontEnd - destroy an instance of a RasFont object vgl_RasFontError - return RasFont object error flag vgl_RasFontCopy - make a copy of a RasFont object -
Raster font creation, attributes, drawing
vgl_RasFontDraw - draw raster font vgl_RasFontLength - query length of a text string vgl_RasFontLoad - load a built-in font vgl_RasFontFreeTypeParam - query FreeType parameters vgl_RasFontFixedFreeType - query FreeType fixed point sizes vgl_RasFontLoadFreeType - load a scaleable FreeType font vgl_RasFontLoadFixedFreeType - load a fixed point FreeType font vgl_RasFontLoadWINFont - load a Microsoft Windows font vgl_RasFontLoadXFont - load a X windows font vgl_RasFontSetBitmap - set a Bitmap object as a font character GetBitmap - get a Bitmap object as a font character vgl_RasFontSetCharWidth - set character width GetCharWidth - get character width vgl_RasFontSetClampSize - set font size minmax limits vgl_RasFontSetMetrics - set width, height, offset and base of font GetMetrics - get width, height, offset and base of font vgl_RasFontSetObject - set attribute object vgl_RasFontSetParami - set raster font parameters GetParami - get raster font parameters vgl_RasFontSetParamf - set raster font parameters GetParamf - get raster font parameters vgl_RasFontSetPixelSize - set raster font pixelsize vgl_RasFontSetSize - set font size multiplier GetSize - get font size multiplier vgl_RasFontSetSpacing - set character spacing GetSpacing - get character spacing
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.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.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.
3.8 Function Descriptions
The currently available RasFont functions are described in detail in this section.RasFont
NAME
*vgl_RasFontBegin - create an instance of a RasFont objectC 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)
RasFont
NAME
vgl_RasFontDraw - draw a raster fontC 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.
RasFont
NAME
vgl_RasFontLength - query length of a text stringC 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.
RasFont
NAME
vgl_RasFontLoad - load one of several built-in raster fontsC 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.
RasFont
NAME
vgl_RasFontFreeTypeParam - query FreeType parametersC 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.
RasFont
NAME
vgl_RasFontFixedFreeType - query FreeType fixed point sizesC 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.
RasFont
NAME
vgl_RasFontLoadFreeType - load a scaleable FreeType fontC 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.
RasFont
NAME
vgl_RasFontLoadFixedFreeType - load a fixed point FreeType fontC 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.
RasFont
NAME
vgl_RasFontLoadWINFont - load a Microsoft Windows fontC 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.
RasFont
NAME
vgl_RasFontLoadXFont - load a X windows fontC 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.
RasFont
NAME
vgl_RasFontSetBitmap - set pointer to bitmap object for a characterC 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)
RasFont
NAME
vgl_RasFontSetCharWidth - set character widthC 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)
RasFont
NAME
vgl_RasFontSetClampSize - set font size minmax limitsC 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.
RasFont
NAME
vgl_RasFontSetMetrics - set width, height, offset and base of fontC 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)
RasFont
NAME
vgl_RasFontSetObject - set pointers to attribute objectsC 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.
RasFont
NAME
vgl_RasFontSetParami - set raster font parametersC 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
=RASFONT_VIRTUALWINDOW Toggle virtual window
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.
Enable a non-physical, virtual window/display using RASFONT_VIRTUALWINDOW. This will disable the automatic num-pixels-per-cm calculation which depends on metrics queried from the physical window/display and instead use the value provided by RASFONT_VIRTUALRESOLUTION specified by vgl_RasFontSetParamf. This is typically used if running on a headless window/display system. By default RASFONT_VIRTUALWINDOW 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.
Get iparam as an output argument using
void vgl_RasFontGetParami (vgl_RasFont *rasfont,
Vint type,
Vint *iparam)
RasFont
NAME
vgl_RasFontSetParamf - set raster font parametersC SPECIFICATION
void vgl_RasFontSetParamf (vgl_RasFont *rasfont,
Vint type,
Vint fparam)
INPUT ARGUMENTS
rasfont Pointer to RasFont object.
type Type of display parameter to set
=RASFONT_VIRTUALRESOLUTION Set virtual window resolution
fparam Specifies the real 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
Set num-pixels-per-cm ratio using RASFONT_VIRTUALRESOLUTION when using a virtual display/window. This is only used if RASFONT_VIRTUALWINDOW is enabled specified by vgl_RasFontSetParami. By default RASFONT_VIRTUALRESOLUTION is set to 37.5.Get fparam as an output argument using
void vgl_RasFontGetParamf (vgl_RasFont *rasfont,
Vint type,
Vint *fparam)
RasFont
NAME
vgl_RasFontSetPixelSize - set raster font pixelsizeC 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.
RasFont
NAME
vgl_RasFontSetSize - set character size multiplierC 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)
RasFont
NAME
vgl_RasFontSetSpacing - set character spacingC 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)
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.
-
Begin and end an instance of an object, return object error flag
*vgl_TextureBegin - create an instance of a Texture object vgl_TextureEnd - destroy an instance of a Texture object vgl_TextureError - return Texture object error flag vgl_TextureCopy - make a copy of a Texture object -
Raster font creation, attributes, drawing
vgl_TextureDef - define texture size Inq - inquire texture size vgl_TextureFBuffer - load texture data from a FBuffer object vgl_TextureLoad - load built-in texture data vgl_TextureSetColor - set texel components GetColor - get texel components vgl_TextureSetColors - set texel components GetColors - get texel components vgl_TextureSetEnv - set texture modulation and blending GetEnv - get texture modulation and blending vgl_TextureSetFilter - set texture filtering GetFilter - get texture filtering vgl_TextureSetTexels - set texel data as 32 bit unsigned integers GetTexels - get texel data as 32 bit unsigned integers vgl_TextureSetWrap - set texture boundary conditions GetWrap - get texture boundary conditions
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.
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.3.12 Function Descriptions
The currently available Texture functions are described in detail in this section.Texture
NAME
*vgl_TextureBegin - create an instance of a Texture objectC 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)
Texture
NAME
vgl_TextureDef - define the size of texel dataC 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.
Texture
NAME
vgl_TextureFBuffer - load texture data from a FBuffer objectC 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.
Texture
NAME
vgl_TextureLoad - load a built-in textureC 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.
Texture
NAME
vgl_TextureSetColor - set texel as floating point color componentsC 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[])
Texture
NAME
vgl_TextureSetColors - set texture data as floating point color componentsC 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[])
Texture
NAME
vgl_TextureSetEnv - set texture mapping environmentC 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)
Texture
NAME
vgl_TextureSetEnvColor - set environment colorC 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])
Texture
NAME
vgl_TextureSetFilter - set minification and magnification filtersC 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)
Texture
NAME
vgl_TextureSetTexels - set texel data as 32 bit unsigned integersC 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[])
Texture
NAME
vgl_TextureSetWrap - set texture boundary conditionsC 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)
