5. Graphics Buffers - ZBuffer,FBuffer,Pixelmap

VglTools Programmer Manual

The z-buffer and frame buffer together implement a device independent framework for manipulating hardware z-buffer and frame buffer contents. The ZBuffer module scan converts and optionally z-buffers graphics primitives. It is primarily used by the end-user to store the contents of a hardware z-buffer in a device independent manner.

The FBuffer module essentially implements a device independent pixelmap. It contains a number of useful functions to read and write color information from/to all VglTools supported hardware platforms. It also has functions to read and write it's contents to a number of industry standard file formats such as JPEG, GIF, TIFF, TARGA, BMP, PNG etc.

Pixelmap is used to store the contents of a hardware frame buffer in a device dependent manner.

5.1 Hidden Line Hidden Surface Removal - ZBuffer

The ZBuffer module scan converts graphics primitives and performs hidden line and hidden surface removal using a z-buffer algorithm. Z-buffering is performed using a 64 bit deep z-buffer which is allocated from main memory. The primary use of the ZBuffer object is to provide access to the hardware z-buffer depth values. The object is also used for all software rendering purposes.

The functions associated with a ZBuffer object are the following.

The ZBuffer module may be used to capture the current z-buffer contents of any hardware graphics device produced by a graphics interface module. Conversely any ZBuffer object may write to the hardware frame buffer controlled by a graphics interface module. The drawing function interfaces for reading and writing ZBuffer objects to a graphics device are: 

    vgl_DrawFunZBufferRead (drawfun,left,right,bottom,top,zbuffer)
    vgl_DrawFunZBufferWrite (drawfun,left,right,bottom,top,zbuffer)
See Chapter 7, Drawing Functions for details.

5.2 Function Descriptions

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

ZBuffer

NAME

*vgl_ZBufferBegin - create an instance of an ZBuffer object

C SPECIFICATION

    vgl_ZBuffer *vgl_ZBufferBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an ZBuffer object. Memory is allocated for the object private data and the pointer to the data is returned. By default all attribute object pointers are NULL.

Destroy an instance of a ZBuffer object using 

         void vgl_ZBufferEnd (vgl_ZBuffer *zbuffer)

Return the current value of a ZBuffer object error flag using 

         Vint vgl_ZBufferError (vgl_ZBuffer *zbuffer)

ZBuffer

NAME

vgl_ZBufferClear - clear entire z-buffer to far value

C SPECIFICATION

    void vgl_ZBufferClear (vgl_ZBuffer *zbuffer)

INPUT ARGUMENTS

    zbuffer       Pointer to ZBuffer object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set all values in z-buffer memory to the far value.

ZBuffer

NAME

vgl_ZBufferDef - define maximum device coordinate dimensions

C SPECIFICATION

    void vgl_ZBufferDef (vgl_ZBuffer *zbuffer,
                         Vint xsize, 
                         Vint ysize)

INPUT ARGUMENTS

    zbuffer       Pointer to ZBuffer object.
    xsize         Width of zbuffer in pixels
    ysize         Height of zbuffer in pixels

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_VALUE is generated if a negative or zero xsize or ysize is specified. VGL_ERROR_MEMORY is generated if z-buffer memory was unable to be allocated.

DESCRIPTION

Define the maximum device coordinate limits of the z-buffer. The dimensions of the z-buffer should match the dimensions of the supporting frame buffer.

Inquire of defined xsize and ysize as output arguments using 

         void vgl_ZBufferInq (vgl_ZBuffer *zbuffer,
                              Vint *xsize, Vint *ysize)

ZBuffer

NAME

vgl_ZBufferSetDepth - set individual zbuffer depth value

C SPECIFICATION

    void vgl_ZBufferSetDepth (vgl_ZBuffer *zbuffer,
                              Vint ix, Vint iy,
                              Vfloat z)

INPUT ARGUMENTS

    zbuffer      Pointer to ZBuffer object.
    ix, iy       Device coordinates of pixel to set.
    z            Depth coordinate

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set depth coordinate at a single pixel. The pixel is addressed by integer device coordinates. Device coordinates range from (0,0) to (xsize-1,ysize-1) where xsize and ysize are the width and height of the zbuffer in pixels.

The depth coordinate lies in the interval [0.,1.].

Get z as an output argument using 

         void vgl_ZBufferGetDepth (vgl_ZBuffer *zbuffer,
                                   Vint ix, Vint iy,
                                   Vfloat *z)

5.3 Software Frame Buffer - FBuffer

Use a FBuffer object to store the output of VglTools modules in a software frame buffer. The depth of the software frame buffer is 32 bits in which 8 bits are allocated to the red, green and blue color components and 8 bits to an alpha channel. The frame buffer is often used in concert with a ZBuffer object and should be given the same device coordinate height and width dimensions. The FBuffer module supports functions to write/read its contents to/from a number of industry standard image file formats such as JPEG, GIF and Targa and video file formats such as MP4 and H264.

The FBuffer module may be used to capture the current frame buffer contents of any hardware graphics device produced by a graphics interface module. Conversely any FBuffer object may write to the hardware frame buffer controlled by a graphics interface module. The drawing function interfaces for reading and writing FBuffer objects to a graphics device are: 

    vgl_DrawFunFBufferRead (drawfun,left,right,bottom,top,fbuffer)
    vgl_DrawFunFBufferWrite (drawfun,left,right,bottom,top,fbuffer)
See Chapter 7, Drawing Functions for details.

The FBuffer module contains a number of image processing functions. The brightness, contrast, and gamma warp may be adjusted using vgl_FBufferBrightContrast and vgl_FBufferGammaWarp . Black and white pixels may be reversed using vgl_FBufferReverseBW. A color image may be converted to grey scale using vgl_FBufferGreyScale. A useful function for adding a border to an image is vgl_FBufferBorder It is possible to cut and paste portions of frame buffer using vgl_FBufferCut and vgl_FBufferPaste. The vgl_FBufferZoom will resize an image. This function is useful for creating thumbnails of an image or other resizing purposes.

The support of the Microsoft Windows AVI image format depends upon external library support. The Windows AVI image file format is supported by vgl_FBufferWriteWINAVI and vgl_FBufferCloseWINAVI. The symbol VKI_WIND_WIN32 must be defined for the function calls to the underlying Windows AVI API to be compiled.

5.4 Reading and Writing PNG, TIFF and JPEG Image Files

The reading and writing support of PNG, TIFF and JPEG image file formats depends upon external library support. These libraries are publicly available. A modified version of the publicly available source for each library is delivered in the vgl/ext subdirectory. The user has the option of compiling and building the libraries from the public source or compiling the source delivered in vgl/ext. The details of these libraries are below.

The PNG (Portable Network Graphics) image format is supported by vgl_FBufferReadPNG and vgl_FBufferWritePNG. The symbol VKI_LIBAPI_PNG or VKI_EXTAPI_PNG must be defined for the function calls to the underlying PNG library to be compiled. Use the symbol VKI_LIBAPI_PNG if using the public source or the symbol VKI_EXTAPI_PNG if using the delivered source. The PNG library in turn depends upon zlib. The source code for the underlying PNG libraries, libpng and zlib, is publicly available. See the following URL for libpng. 

    http://www.libpng.org
See the following URL for zlib. 
    http://www.gzip.org/zlib

The TIFF file format is supported by vgl_FBufferReadTIFF. The symbol VKI_LIBAPI_TIFF or VKI_EXTAPI_TIFF must be defined for the function calls to the underlying TIFF library to be compiled. The writing of TIFF files is supported without using an external library. However if VKI_LIBAPI_TIFF is defined the writing of TIFF files will use the external library functions. Use the symbol VKI_LIBAPI_TIFF if using the public source or the symbol VKI_EXTAPI_TIFF if using the delivered source. The source code for the underlying TIFF libraries libtiff and zlib, is publicly available. See the following URL. 

    http://www.remotesensing.org/libtiff
The JPEG file format is supported by vgl_FBufferReadJPEG. The symbol VKI_LIBAPI_JPEG or VKI_EXTAPI_JPEG must be defined for the function calls to the underlying JPEG library to be compiled. The writing of JPEG files is supported without using an external library. However if VKI_LIBAPI_JPEG is defined the writing of JPEG files will use the external library functions. Use the symbol VKI_LIBAPI_JPEG if using the public source or the symbol VKI_EXTAPI_JPEG if using the delivered source.

5.5 Writing Video Files

The FFMPEG video package supports many industry standard video file formats such as MP4 and MOV. The symbol VKI_LIBAPI_FFMPEG must be defined for the function calls to the underlying FFMPEG library to be compiled. The source code and prebuilt libraries are publically available. See the following URL. 
    http://www.ffmpeg.org

5.6 Function Descriptions

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

FBuffer

NAME

*vgl_FBufferBegin - create an instance of a FBuffer object

C SPECIFICATION

    vgl_FBuffer *vgl_FBufferBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a FBuffer object. Memory is allocated for the object private data and the pointer to the data is returned. All attribute object pointers are NULL and the current color is set to 0. The frame buffer dimensions must be defined before it can receive display primitives. Use vgl_FBufferDef to define the frame buffer dimensions.

Destroy an instance of a FBuffer object using 

         void vgl_FBufferEnd (vgl_FBuffer *fbuffer)

Return the current value of a FBuffer object error flag using 

         Vint vgl_FBufferError (vgl_FBuffer *fbuffer)
Make a copy of a FBuffer object. The private data from the fromfbuffer object is copied to the fbuffer object. Any previous private data in fbuffer is lost. 
         void vgl_FBufferCopy (vgl_FBuffer *fbuffer,
                               vgl_FBuffer *fromfbuffer)

FBuffer

NAME

vgl_FBufferBorder - add a constant color border

C SPECIFICATION

    void vgl_FBufferBorder (vgl_FBuffer *fbuffer,
                            Vint borderwidth)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    borderwidth  Width of border in pixels

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_VALUE is generated if a value of borderwidth is input which is less than or equal to 1 or is greater than or equal to either dimension of the image.

DESCRIPTION

Set pixels around border of image to the current color. The width of the border is specified by borderwidth. Use vgl_FBufferColor to set the current color.

FBuffer

NAME

vgl_FBufferBrightContrast - adjust brightness and contrast

C SPECIFICATION

    void vgl_FBufferBrightContrast (vgl_FBuffer *fbuffer,
                                    Vfloat bright,
                                    Vfloat contrast)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    bright       Brightness bias.
    contrast     Contrast factor.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Adjust brightness and contrast of image. The brightness, bright, is a constant bias in the range [-1.,1.] which is added to each of the red, green and blue color components. A brightness of 0. does not alter the brightness. The contrast is a factor close to unity which generally retains the average brightness of an image but alters the extremes of brightness variation. A contrast of 1. does not alter the contrast. In all cases the resulting color is clamped to the interval [0.,1.].

The equation applied to each component, c, of the color is: 

         c = (c + bright - .5) * contrast + .5

FBuffer

NAME

vgl_FBufferClear - clear rectangle of frame buffer to current color

C SPECIFICATION

    void vgl_FBufferClear (vgl_FBuffer *fbuffer,
                           Vint left, Vint right, 
                           Vint bottom, Vint top)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    left         Left device coordinate limit of rectangle
    right        Right device coordinate limit of rectangle
    bottom       Bottom device coordinate limit of rectangle
    top          Top device coordinate limit of rectangle

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set pixels in a rectangular area of frame buffer memory to the current color. The rectangular area is defined by left, right, bottom and top. If all device coordinate limits are input as zero then the entire area of the frame buffer is cleared. Use vgl_FBufferColor to set the current color.

FBuffer

NAME

vgl_FBufferColor - set RGB components of current color

C SPECIFICATION

    void vgl_FBufferColor (vgl_FBuffer *fbuffer,
                           Vfloat c[3])

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    c            RGB components of current color.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set RGB components of current color. The RGB components lie in the interval [0.,1.].

FBuffer

NAME

vgl_FBufferCut - cut out a frame buffer

C SPECIFICATION

    void vgl_FBufferCut (vgl_FBuffer *fbuffer,
                         Vint xorig, Vint yorig,
                         vgl_FBuffer *cutfbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    xorig,yorig  X and y pixel location in fbuffer from which to cut image.

OUTPUT ARGUMENTS

    cutfbuffer   Pointer to FBuffer object into which cut is written.

DESCRIPTION

Cut out a portion of a frame buffer object, fbuffer, and write it to another frame buffer object, cutbuffer. The width and height of the image to be cut is determined by the size of cutfbuffer. The origin in fbuffer of the image to be cut is specified by xorig and yorig. Any pixels addressed outside of the size limits of fbuffer are undefined in cutfbuffer. Paste in an image using vgl_FBufferPaste.

FBuffer

NAME

vgl_FBufferDef - define frame buffer dimensions

C SPECIFICATION

    void vgl_FBufferDef (vgl_FBuffer *fbuffer, 
                         Vint xsize, 
                         Vint ysize)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    xsize        Width of frame buffer in pixels
    ysize        Height of frame buffer in pixels

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_VALUE is generated if a negative or zero xsize or ysize is specified. VGL_ERROR_MEMORY is generated if frame buffer memory allocation fails.

DESCRIPTION

Set the dimensions of the frame buffer. Any previous contents of the fbuffer object are lost. Frame buffer memory is allocated at this time. Since the amount of memory allocated may be considerable, it is wise to check the error status using vgl_FBufferError immediately after returning from this function. The function may be called anytime to change frame buffer dimensions.

Inquire of defined xsize and ysize as output arguments using 

         void vgl_FBufferInq (vgl_FBuffer *fbuffer,
                              Vint *xsize,
                              Vint *ysize)

FBuffer

NAME

vgl_FBufferGammaWarp - perform gamma correction

C SPECIFICATION

    void vgl_FBufferGammaWarp (vgl_FBuffer *fbuffer,
                               Vfloat gamma)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    gamma        Gamma correction factor

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_VALUE is generated if a value of gamma is input which is less than or equal to 0. or is greater than or equal to 100.

DESCRIPTION

Perform gamma correction. Gamma correction adjusts the red, green and blue components of color to correct for non-linear response of graphics display devices to color.

The equation applied to each component, c, of the color is: 

         c = c ** 1./gamma

FBuffer

NAME

vgl_FBufferGreyScale - convert to gray scale

C SPECIFICATION

    void vgl_FBufferGreyScale (vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Convert to gray scale. A weighed sum of the red, green and blue components of the color at each pixel is computed which represents the gray scale. This value is then assigned to all the color components at that pixel.

The equation for grayscale is: 

         grayscale = .3*red + .5*green + .2*blue;

FBuffer

NAME

vgl_FBufferPaste - paste in a frame buffer

C SPECIFICATION

    void vgl_FBufferPaste (vgl_FBuffer *fbuffer,
                           Vint xorig, Vint yorig,
                           vgl_FBuffer *pastefbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    xorig,yorig  X and y pixel location in fbuffer in which to paste image.

OUTPUT ARGUMENTS

    pastefbuffer Pointer to FBuffer object from which paste is read.

DESCRIPTION

Paste in a frame buffer object, pastefbuffer, and write it to frame buffer object, fbuffer. The width and height of the image to be pasted is determined by the size of pastefbuffer. The origin in fbuffer of the image to be pasted is specified by xorig and yorig. Any pixels addressed outside of the size limits of fbuffer are not pasted. Cut out an image using vgl_FBufferCut.

FBuffer

NAME

vgl_FBufferReverseBW - reverse black and white pixels in a frame buffer

C SPECIFICATION

    void vgl_FBufferReverseBW (vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Reverse the black and white pixels in a frame buffer object. A white pixel is defined as 0x00ffffff and a black pixel by 0x00000000. If the image in the frame buffer object has been dithered, then regions of color close to white and black may not produce satisfactory results.

FBuffer

NAME

vgl_FBufferScale - scale a frame buffer by an integer factor

C SPECIFICATION

    void vgl_FBufferScale (vgl_FBuffer *fbuffer,
                           Vint fac,
                           vgl_FBuffer *scafbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    fac          Integer scaling factor.

OUTPUT ARGUMENTS

    scafbuffer   Pointer to FBuffer object into which scaled frame buffer
                 is written.

DESCRIPTION

Scale a frame buffer object, fbuffer, by an integer factor. To change the dimensions of a frame buffer in a general way use vgl_FBufferZoom.

FBuffer

NAME

vgl_FBufferRotate - rotate counterclockwise by 90 degrees

C SPECIFICATION

    void vgl_FBufferRotate (vgl_FBuffer *fbuffer,
                            vgl_FBuffer *rotfbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    rotfbuffer   Pointer to FBuffer object into which rotated frame buffer
                 is written.

ERRORS

VGL_ERROR_OPERATION is generated if the width and height of the source frame buffer are not equal to the height and width respectively of the destination frame buffer.

DESCRIPTION

Rotate a frame buffer object, fbuffer, counterclockwise by 90 degrees and write it to frame buffer object, rotfbuffer. The width and height of the destination frame buffer, rotfbuffer, must be equal to the height and width respectively of the source frame buffer, fbuffer. This operation is useful for fitting a frame buffer image to the aspect ratio of a printed page before sending it to a printer. The source frame buffer object, fbuffer, is unchanged by this function.

FBuffer

NAME

vgl_FBufferSetColor - set a frame buffer RGB color value

C SPECIFICATION

    void vgl_FBufferSetColor (vgl_FBuffer *fbuffer,
                              Vint ix, Vint iy,
                              Vfloat c[3])

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    ix, iy       Device coordinates of pixel to set.
    c            RGB components of color.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set RGB components of color at a single pixel. The pixel is addressed by integer device coordinates. Device coordinates range from (0,0) to (xsize-1,ysize-1) where xsize and ysize are the width and height of the frame buffer in pixels.

The RGB components lie in the interval [0.,1.]. Each color is represented by 8 bits. The bits for each color are packed in an unsigned integer with red occupying the least significant byte.

Get c as an output argument using 

         void vgl_FBufferGetColor (vgl_FBuffer *fbuffer,
                                   Vint ix, Vint iy,
                                   Vfloat c[3])

FBuffer

NAME

vgl_FBufferSetColorAlpha - set a frame buffer RGBA color value

C SPECIFICATION

    void vgl_FBufferSetColorAlpha (vgl_FBuffer *fbuffer,
                                   Vint ix, Vint iy,
                                   Vfloat c[4])

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    ix, iy       Device coordinates of pixel to set.
    c            RGBA components of color.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set RGBA components of color and alpha at a single pixel. The pixel is addressed by integer device coordinates. Device coordinates range from (0,0) to (xsize-1,ysize-1) where xsize and ysize are the width and height of the frame buffer in pixels.

The RGBA components lie in the interval [0.,1.]. Internally each component is represented by 8 bits. The bits for each component are packed in an unsigned integer with red occupying the least significant byte.

Get c as an output argument using 

         void vgl_FBufferGetColorAlpha (vgl_FBuffer *fbuffer,
                                        Vint ix, Vint iy,
                                        Vfloat c[4])

FBuffer

NAME

vgl_FBufferSetParamf - set file interface parameters

C SPECIFICATION

    void vgl_FBufferSetParamf (vgl_FBuffer *fbuffer,
                               Vint type,
                               Vint fparam)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    type         Type of display parameter to set
                 =FBUFFER_DELAYSECONDS   Delay time in seconds
    fparam       Specifies the float value that type will be set to.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_ENUM is generated if an improper type is specified. VGL_ERROR_VALUE is generated if delay time less than zero is specified.

DESCRIPTION

Specify a float delay time in seconds to be applied to images appended to a GIF file or Windows AVI file. By default FBUFFER_DELAYSECONDS is set to .05.

FBuffer

NAME

vgl_FBufferSetParami - set file interface parameters

C SPECIFICATION

    void vgl_FBufferSetParami (vgl_FBuffer *fbuffer,
                               Vint type,
                               Vint iparam)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    type         Type of display parameter to set
                 =FBUFFER_BITRATE        Bit rate for H264 MP4
                 =FBUFFER_INTERLACE      Interlace image file
                 =FBUFFER_LOOPS          Number of times to loop animation
                 =FBUFFER_LOOPSFLAG      Looping flag
                 =FBUFFER_GRAYSCALE      Gray scale flag
                 =FBUFFER_COMPFACT       Compression factor
                 =FBUFFER_AVICOMPFACT    AVI compression factor
                 =FBUFFER_AVICOMPTYPE    AVI compression type
                 =FBUFFER_GIFCOMPTYPE    GIF compression type
                 =FBUFFER_GIFCMAPTYPE    GIF base colormap type
                 =FBUFFER_GIFCMAPMATCH   GIF Attempt exact colormap
                 =FBUFFER_TIFFCOMPTYPE   TIFF compression type
    iparam       Specifies the integer value that type will be set to.
                 =VGL_ON                 Enable
                 =VGL_OFF                Disable
                 =FBUFFER_AVICOMP_INTELINDEO INTEL Indeo
                 =FBUFFER_AVICOMP_CINEPAK    Cinepak
                 =FBUFFER_AVICOMP_MSVIDEO    Microsoft Video 1
                 =FBUFFER_GIFCOMP_RLE        Run length encoding (not patented)
                 =FBUFFER_GIFCOMP_LZW        LZW compression (patented)
                 =FBUFFER_GIFCMAP_DITHER     Use a dithered colormap
                 =FBUFFER_GIFCOMP_332RGB     Use a 332 bit RGB colormap
                 =FBUFFER_TIFFCOMP_NONE      Use no compression
                 =FBUFFER_TIFFCOMP_LZW       LZW compression
                 =FBUFFER_TIFFCOMP_DEFLATE   Deflation compression
                 =FBUFFER_TIFFCOMP_NATIVE    Native compression

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

Enable an interlaced output image file. This option effects output GIF and PNG files only. By default FBUFFER_INTERLACE is set to VGL_ON.

The parameter FBUFFER_BITRATE set the bit rate used in H264 encoded MP4 files. The higher the bit rate the higher the vides quality resulting in a larger file size By default FBUFFER_BITRATE is set to 200000.

Specify a the integer number of times the images in an animated GIF file are to be replayed. A value of zero results in an infinite number of loops. Note that the looping facility for GIF files is a Netscape Navigator extension. By default FBUFFER_LOOPS is set to 0. Use FBUFFER_LOOPSFLAG to enable looping. By default FBUFFER_LOOPSFLAG is set to VGL_OFF.

Specify a flag to turn gray scale image writing on or off. If gray scale is enabled the color contents of the frame buffer will be written to image format in gray scale. This parameter affects all image format writing functions such as vgl_FBufferWriteGIF. By default FBUFFER_GRAYSCALE is set to VGL_OFF.

The compression factor, FBUFFER_COMPFACT is an integer number of percent suggesting a target compression factor. This parameter affects the writing of JPEG and AVI image files. By default FBUFFER_COMPFACT is set to 85.

The parameters, FBUFFER_AVICOMPFACT and FBUFFER_AVICOMPTYPE affect the writing of AVI files using the function vgl_FBufferWriteWINAVI. The compression type, FBUFFER_AVICOMPTYPE selects video compression. The recommended compression type for scientific and engineering graphics is FBUFFER_AVICOMP_MSVIDEO. By default FBUFFER_AVICOMPTYPE is set to FBUFFER_AVICOMP_NONE.

The parameter FBUFFER_GIFCOMPTYPE affects the writing of GIF files using the function vgl_FBufferWriteGIF. The importance of this parameter is due to the existence of a Unisys patent on the LZW compression algorithm. The value FBUFFER_GIFCOMP_RLE indicates the use of a non-patented run length encoding compression algorithm. The value FBUFFER_GIFCOMP_ZLW indicates the use of the patented LZW compression algorithm. By default FBUFFER_GIFCOMPTYPE is set to FBUFFER_GIFCOMP_LZW.

The parameter FBUFFER_TIFFCOMPTYPE affects the writing of TIFF files using the function vgl_FBufferWriteTIFF. By default FBUFFER_TIFFCOMPTYPE is set to FBUFFER_TIFFCOMP_LZW. Note that some Microsoft Windows applications do not handle the default compression properly. Use FBUFFER_TIFFCOMP_NATIVE if consistent results with Windows applications is required.

The parameters FBUFFER_GIFCMAPTYPE and FBUFFER_GIFCMAPMATCH affect the type of color map to be generated for writing GIF files using the function vgl_FBufferWriteGIF. If FBUFFER_GIFCMAPMATCH is enabled, then an attempt is made to generate a color map in which each color in the image is exactly represented in the color map. This will succeed only if the number of unique colors in the image is less than or equal to 256. If an exact match is not possible or FBUFFER_GIFCMAPMATCH is disabled, then the color map generated is determined by FBUFFER_GIFCMAPTYPE. By default FBUFFER_GIFCMAPTYPE is set to FBUFFER_GIFCMAP_DITHER and FBUFFER_GIFCMAPMATCH is set to VGL_OFF.

FBuffer

NAME

vgl_FBufferSetPixel - set a frame buffer pixel value

C SPECIFICATION

    void vgl_FBufferSetPixel (vgl_FBuffer *fbuffer,
                              Vint ix, Vint iy,
                              Vuint value)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    ix, iy       Device coordinates of pixel to set.
    value        Value

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set a value in a specified pixel in a frame buffer. The pixel is addressed by integer device coordinates. Device coordinates range from (0,0) to (xsize-1,ysize-1) where xsize and ysize are the width and height of the frame buffer in pixels.

Each color is represented by 8 bits. The bits for each color are packed in an unsigned integer with red occupying the least significant byte.

Get value as an output argument using 

         void vgl_FBufferGetPixel (vgl_FBuffer *fbuffer,
                                   Vint ix, Vint iy,
                                   Vuint *value)

FBuffer

NAME

vgl_FBufferOpenFFMPEG - open FFMPEG supported video file

C SPECIFICATION

    void vgl_FBufferOpenFFMPEG (vgl_FBuffer *fbuffer,
                                Vint codectype,
                                Vint filetype,
                                Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    codectype    Video coded type
                 =FBUFFER_FFMPEG_CODEC_MPEG4     MPEG4 codec
                 =FBUFFER_FFMPEG_CODEC_H264      H264 codec
                 =FBUFFER_FFMPEG_CODEC_PNG       PNG codec
                 =FBUFFER_FFMPEG_CODEC_QTRLE     QTRLE codec
    filetype     Video coded type
                 =FBUFFER_FFMPEG_MP4     MP4 file
                 =FBUFFER_FFMPEG_MOV     QuickTime MOV format
    pathname     Name of video file to open

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_ENUM is generated if an improper codectype or filetype is specified. VGL_ERROR_ENUM is generated if FBUFFER_FFMPEG_CODEC_PNG or FBUFFER_FFMPEG_CODEC_QTRLE are used along with filetype FBUFFER_FFMPEG_MP4 is used. VGL_ERROR_FILE is generated if an improper pathname is specified. VGL_ERROR_OPERATION if the image file sizes are not even numbers.

DESCRIPTION

Open a video file of type filetype with codec codectype. 
     image horizontal and vertical
sizes must be even numbers. Write individual images using vgl_FBufferWriteFFMPEG. Close the video file using vgl_FBufferCloseFFMPEG.

MP4 files can be encoded with either the MPEG4 or the H264 encoders, while MOV files can be encoded with any of the provided encoders.

FBuffer

NAME

vgl_FBufferWriteFFMPEG - write FFMPEG supported video file

C SPECIFICATION

    void vgl_FBufferWriteFFMPEG (vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION if the image file has not been opened.

DESCRIPTION

Write image contents to currently open video file. Open the video file using vgl_FBufferOpenFFMPEG.

FBuffer

NAME

vgl_FBufferCloseFFMPEG - close FFMPEG supported video file

C SPECIFICATION

    void vgl_FBufferCloseFFMPEG (vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION if the image file has not been opened.

DESCRIPTION

Close currently open video file.

FBuffer

NAME

vgl_FBufferReadBMP,vgl_FBufferWriteBMP - Read/Write BMP image file.

C SPECIFICATION

    void vgl_FBufferReadBMP (vgl_FBuffer *fbuffer,
                             Vchar *pathname)
    
    void vgl_FBufferWriteBMP (vgl_FBuffer *fbuffer,
                              Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are read/written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified or, if reading, the file data is in an unrecognizable format. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading or writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a BMP file. If reading, the previous contents of the frame buffer are lost and the frame buffer is redefined and reallocated to the dimensions of the frame buffer on the file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferWriteEPS - Write frame buffer contents to Encapsulated Postscript

C SPECIFICATION

    void vgl_FBufferWriteEPS (vgl_FBuffer *fbuffer,
                              Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified. VGL_ERROR_OPERATION is generated if any other error occurs during image file writing.

DESCRIPTION

Write the contents of a frame buffer to an Encapsulated PostScript file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferReadGIF,vgl_FBufferWriteGIF,vgl_FBufferAppendGIF - GIF file interface

C SPECIFICATION

    void vgl_FBufferReadGIF (vgl_FBuffer *fbuffer,
                             Vchar *pathname)
    
    void vgl_FBufferWriteGIF (vgl_FBuffer *fbuffer,
                              Vchar *pathname)
    
    void vgl_FBufferAppendGIF (vgl_FBuffer *fbuffer,
                               Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are read/written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified or, if reading, the file data is in an unrecognizable format. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading or writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a GIF file. If reading, the previous contents of the frame buffer are lost and the frame buffer is redefined and reallocated to the dimensions of the frame buffer on the file.

An image may be appended to an existing GIF file to produce an "animated" GIF file using vgl_FBufferAppendGIF. The appended GIF file will use the same grayflag that was used to create the first image on the file. Use vgl_FBufferSetParami and vgl_FBufferSetParamf to control delay time, number of loops, interlacing, etc. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferReadJPEG,vgl_FBufferWriteJPEG - Read/Write JPEG image file

C SPECIFICATION

    void vgl_FBufferReadJPEG (vgl_FBuffer *fbuffer,
                              Vchar *pathname)
    
    void vgl_FBufferWriteJPEG (vgl_FBuffer *fbuffer,
                               Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading/writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a JPEG formatted file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami. The JPEG file is generated using a "lossy" compression. Set the compression factor using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferWritePict - Write frame buffer contents to Pict formatted file

C SPECIFICATION

    void vgl_FBufferWritePict (vgl_FBuffer *fbuffer,
                               Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified. VGL_ERROR_OPERATION is generated if any other error occurs during image file writing.

DESCRIPTION

Write the contents of a frame buffer to a Pict formatted file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferReadPNG,vgl_FBufferWritePNG - PNG file interface

C SPECIFICATION

    void vgl_FBufferReadPNG (vgl_FBuffer *fbuffer,
                             Vchar *pathname)
    
    void vgl_FBufferWritePNG (vgl_FBuffer *fbuffer,
                              Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are read/written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified or, if reading, the file data is in an unrecognizable format. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading or writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a PNG file. If reading, the previous contents of the frame buffer are lost and the frame buffer is redefined and reallocated to the dimensions of the frame buffer on the file.

FBuffer

NAME

vgl_FBufferReadSGI,vgl_FBufferWriteSGI - Read/Write SGI RGB image file

C SPECIFICATION

    void vgl_FBufferReadSGI (vgl_FBuffer *fbuffer,
                             Vchar *pathname)
    
    void vgl_FBufferWriteSGI (vgl_FBuffer *fbuffer,
                              Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are read/written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified or, if reading, the file data is in an unrecognizable format. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading or writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a SGI RGB file. If reading, the previous contents of the frame buffer are lost and the frame buffer is redefined and reallocated to the dimensions of the frame buffer on the file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferWriteSVG - write to Scaleable Vector Graphics file

C SPECIFICATION

    void vgl_FBufferWriteSVG (vgl_FBuffer *fbuffer,
                              Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if any error occurs during image file writing.

DESCRIPTION

Write the contents of a frame buffer to a file in Scaleable Vector Graphics format.

FBuffer

NAME

vgl_FBufferReadTarga,vgl_FBufferWriteTarga - Read/Write Targa image file

C SPECIFICATION

    void vgl_FBufferReadTarga (vgl_FBuffer *fbuffer,
                               Vchar *pathname)
    
    void vgl_FBufferWriteTarga (vgl_FBuffer *fbuffer,
                                Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are read/written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified or, if reading, the file data is in an unrecognizable format. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading or writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a Targa file. If reading, the previous contents of the frame buffer are lost and the frame buffer is redefined and reallocated to the dimensions of the frame buffer on the file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferReadTIFF,vgl_FBufferWriteTIFF - Read/Write Tiff image file

C SPECIFICATION

    void vgl_FBufferReadTIFF (vgl_FBuffer *fbuffer,
                              Vchar *pathname)
    
    void vgl_FBufferWriteTIFF (vgl_FBuffer *fbuffer,
                               Vchar *pathname)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pathname     Name of file to which frame buffer contents are written

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_FILE is generated if an improper pathname is specified. VGL_ERROR_OPERATION is generated if any other error occurs during image file reading/writing.

DESCRIPTION

Read/Write the contents of a frame buffer from/to a Tiff formatted file. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

FBuffer

NAME

vgl_FBufferWriteWINAVI - write to Microsoft Windows AVI stream

C SPECIFICATION

    void vgl_FBufferWriteWINAVI (vgl_FBuffer *fbuffer,
                                 PAVIFILE *avifile)
    void vgl_FBufferCloseWINAVI (vgl_FBuffer *fbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    avifile      PAVIFILE pointer to AVI file

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_NULLOBJECT is generated if avifile is NULL. VGL_ERROR_OPERATION is generated if any AVIFile or AVIStream operation fails. VGL_ERROR_MEMORY is generated if unable to allocate bitmap memory.

DESCRIPTION

Write the contents of a frame buffer to Windows AVI file stream. The first call to vgl_FBufferWriteWINAVI creates the AVI video stream and writes the contents of the frame buffer to the stream. Each subsequent call to vgl_FBufferWriteWINAVI adds the contents of the frame buffer as an additional sample to the video stream. Call vgl_FBufferCloseWINAVI to release the video stream. At this point vgl_FBufferWriteWINAVI may be called to create a new AVI stream and write video samples until vgl_FBufferCloseWINAVI is called to close the stream and so on. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami.

The AVI file may be compressed if desired. Set the compression type and factor using vgl_FBufferSetParami. By default the AVI is not compressed.

Before these functions may be called the Microsoft Windows AVI file interface must be initialized. Once initialized, an AVI file is opened as follows: 

    #include <VfW.h>
    
       PAVIFILE avifile;
                       /* initialize AVI interface only once in application */ 
       AVIFileInit ();
                       /* open any number of AVI files */ 
       AVIFileOpen (&avifile,"myfile.avi",OF_CREATE|OF_WRITE,NULL);

Note that the initialization is performed only once during an application. At this point several samples may be written to a video stream by calling vgl_FBufferWriteWINAVI for each sample and calling vgl_FBufferCloseWINAVI to close the video stream. After all samples are written to the AVI file, the file must be released. Once all AVI file processing is complete, the AVI file interface must be exited as follows: 

                       /* release each AVI file when finished writing samples */ 
       AVIFileRelease (avifile);
                       /* exit AVI interface only once in application */ 
       AVIFileExit ();

The Microsoft Windows library vfw32.lib must be used at link time to satisfy the external references to the AVI system.

FBuffer

NAME

vgl_FBufferReadWINDIB - read from Microsoft Windows memory DIB

C SPECIFICATION

    void vgl_FBufferReadWINDIB (vgl_FBuffer *fbuffer,
                                BITMAPINFO *binfo,
                                LPVOID bdata)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    binfo        BITMAPINFO structure with members set.
    bdata        Pointer to allocated memory which holds image data

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_NULLOBJECT is generated if either binfo or bdata is NULL. VGL_ERROR_OPERATION is generated if any members of the binfo structure are improper.

DESCRIPTION

Read the contents of a Windows DIB memory structure. The BITMAPINFOHEADER must contain the same values as described under vgl_FBufferWriteWINDIB.

FBuffer

NAME

vgl_FBufferWriteWINDIB - write to Microsoft Windows memory DIB

C SPECIFICATION

    void vgl_FBufferWriteWINDIB (vgl_FBuffer *fbuffer,
                                 BITMAPINFO *binfo,
                                 LPVOID bdata)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    binfo        BITMAPINFO structure with members set.

OUTPUT ARGUMENTS

    bdata        Pointer to allocated memory to hold image data

ERRORS

VGL_ERROR_NULLOBJECT is generated if either binfo or bdata is NULL. VGL_ERROR_OPERATION is generated if any members of the binfo structure are improper.

DESCRIPTION

Write the contents of a frame buffer to Windows DIB memory structures. The image will be written in grayscale if FBUFFER_GRAYSCALE is enabled using vgl_FBufferSetParami. The BITMAPINFOHEADER must contain the following values. 
       DWORD  biSize          = sizeof(BITMAPINFOHEADER)
       LONG   biWidth         = xsize, width of frame buffer in pixels
       LONG   biHeight        = ysize, height of frame buffer in pixels
       WORD   biPlanes        = 1 
       WORD   biBitCount      = 16 or 24
       DWORD  biCompression   = BI_RGB 
       DWORD  biSizeImage     = (((biWidth * biBitCount) + 31) & ~31) >> 3

Get the current width and height of the frame buffer using vgl_FBufferInq. The use of a biBitCount of 16 is recommended for compatibility with most printers. The pointer to the image data, bdata, must have been allocated to be at least biSizeImage bytes.

When using Microsoft Foundation Classes (MFC). Printing can be implemented using this function. In the view class header add the following: 

       vgl_FBuffer *m_fbuffer;
       BITMAPINFO   m_binfo;
       LPVOID       m_bdata;

In the view class OnPreparePrinting grab the frame buffer and write it to a DIB data structure as follows: 

       Vint width;
       Vint height;
       long rowsize;
       Vint ierr;
    
                       /* Instance FBuffer object and grab frame buffer contents */ 
       m_fbuffer = vgl_FBufferBegin ();
       vgl_DrawFunSetWindow (m_dfdv);
       vgl_DrawFunFBufferRead (m_dfdv,0,0,0,0,m_fbuffer);
       vgl_FBufferInq (m_fbuffer,&width,&height);
    
                       /* Fill in binfo data structure */ 
       memset(&m_binfo,0,sizeof(BITMAPINFO));
       m_binfo.bmiHeader.biSize   = sizeof(BITMAPINFOHEADER);
       m_binfo.bmiHeader.biHeight = height;
       m_binfo.bmiHeader.biWidth  = width;
       m_binfo.bmiHeader.biPlanes = 1;
       m_binfo.bmiHeader.biBitCount    = 16;
       m_binfo.bmiHeader.biCompression = BI_RGB;
       rowsize = ((((width * m_binfo.bmiHeader.biBitCount) + 31) & ~31) >> 3);
       m_binfo.bmiHeader.biSizeImage = rowsize * height;
       m_bdata = (LPVOID)malloc(m_binfo.bmiHeader.biSizeImage);
                       /* Write frame buffer to DIB data structure */ 
       vgl_FBufferWriteWINDIB (m_fbuffer,&m_binfo,m_bdata,0);

In the view class OnPrint apply any scale factors to the DIB and send to printer. 

       float fact;
       Vint width;
       Vint height;
    
       vgl_FBufferInq (m_fbuffer,&width,&height);
    
       fact = (float)GetDeviceCaps(pDC->GetSafeHdc(),HORZRES)/(float)width;
                       /* Shrink it by 75 percent as an example */ 
       fact *= .75;
                       /* Send to printer */ 
       StretchDIBits (pDC->GetSafeHdc(),
                      0,0,(int)fact*width,(int)fact*height,
                      0,0,width,height,
                      m_bdata,&m_binfo, DIB_RGB_COLORS, SRCCOPY);

In the view class OnEndPrinting free objects and memory as follows: 

       vgl_FBufferEnd (m_fbuffer);
       free(m_bdata);

FBuffer

NAME

vgl_FBufferPixelmap - convert Pixelmap object

C SPECIFICATION

    void vgl_FBufferPixelmap (vgl_FBuffer *fbuffer,
                              vgl_Pixelmap *pixelmap)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.
    pixelmap     Pointer to Pixelmap object.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Convert the contents of a device dependent Pixelmap object to the device independent FBuffer form. This feature is currently only implemented for Pixelmap objects created by the OpenGLDev object.

FBuffer

NAME

vgl_FBufferZoom - change the dimensions of a frame buffer

C SPECIFICATION

    void vgl_FBufferZoom (vgl_FBuffer *fbuffer,
                          vgl_FBuffer *zoomfbuffer)

INPUT ARGUMENTS

    fbuffer      Pointer to FBuffer object.

OUTPUT ARGUMENTS

    zoomfbuffer  Pointer to FBuffer object into which frame buffer of
                 changed dimensions is written.

DESCRIPTION

Change the dimensions of a frame buffer object, fbuffer, and write it to frame buffer object, zoomfbuffer. The width and height of the destination frame buffer is determined by the size of zoomfbuffer. The filtering method used is a one pass, two dimensional convolution. The source frame buffer object, fbuffer, is unchanged by this function. To simply scale a frame buffer by an integer factor use vgl_FBufferScale.

5.7 Device Dependent Frame Buffer Storage - Pixelmap

Pixelmap objects are used in conjunction with VglTools device interface modules to store the frame (color) buffer or z (depth) buffer contents of a device in a device dependent manner. The primary design goal is to achieve high transfer rates when transferring the contents of a Pixelmap object to and from a hardware buffer. The functions associated with a Pixelmap object are the following.

The Pixelmap module may be used to store the frame buffer or zbuffer contents of any hardware graphics device produced by a graphics interface module. Since the frame buffer or zbuffer contents stored in a Pixelmap object are device dependent, the contents of a Pixelmap object read from one graphics device should not be written to another. The storage allocation and buffer transfer to Pixelmap objects is done by the device interface modules. The drawing function interface for allocating storage in a Pixelmap object is: 

    vgl_DrawFunPixelmapCreate (drawfun,pixelmap)
    vgl_DrawFunPixelmapDestroy (drawfun,pixelmap)
Transfer of frame buffer or zbuffer contents is performed by: 

    vgl_DrawFunPixelmapRead (drawfun,pixelmap)
    vgl_DrawFunPixelmapWrite (drawfun,pixelmap)
The default buffer type is the frame buffer. Use vgl_PixelmapSetBuffer to set the buffer type. By default the entire buffer is read and written by the device interface functions above. Use vgl_PixelmapSetSize to specify the size of the pixelmap in pixel coordinates to be read and written. The origin of the pixelmap in the device interface window may be specified using vgl_PixelmapSetOrigin.

See Chapter 7, Drawing Functions for details.

5.8 Function Descriptions

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

Pixelmap

NAME

*vgl_PixelmapBegin - create an instance of a Pixelmap object

C SPECIFICATION

    vgl_Pixelmap *vgl_PixelmapBegin ()

ARGUMENTS

    None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of a Pixelmap object. Memory is allocated for the object private data and the pointer to the data is returned. By default the origin is 0,0 and the size is 0,0. A size of 0,0 will default to the current window size.

Destroy an instance of a Pixelmap object using 

         void vgl_PixelmapEnd (vgl_Pixelmap *pixelmap)

Return the current value of a Pixelmap object error flag using 

         Vint vgl_PixelmapError (vgl_Pixelmap *pixelmap)

Pixelmap

NAME

vgl_PixelmapSetBuffer - set pixelmap buffer type

C SPECIFICATION

    void vgl_PixelmapSetBuffer (vgl_Pixelmap *pixelmap,
                                Vint buffer)

INPUT ARGUMENTS

    pixelmap     Pointer to Pixelmap object.
    buffer       Buffer type
                 =PIXELMAP_FBUFFER       Frame (color) buffer
                 =PIXELMAP_ZBUFFER       Z (depth) buffer

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set the buffer type of the pixelmap for all read and write operations to a device interface using the PixelmapRead and PixelmapWrite drawing functions. The default buffer type is PIXELMAP_FBUFFER.

Get buffer as an output argument using 

         void vgl_PixelmapGetBuffer (vgl_Pixelmap *pixelmap,
                                     Vint *buffer)

Pixelmap

NAME

vgl_PixelmapSetOrigin - set origin of pixelmap

C SPECIFICATION

    void vgl_PixelmapSetOrigin (vgl_Pixelmap *pixelmap,
                                Vint xorig,
                                Vint yorig)

INPUT ARGUMENTS

    pixelmap     Pointer to Pixelmap object.
    xorig,yorig  Lower left hand corner of pixelmap in device coordinates.

OUTPUT ARGUMENTS

    None

DESCRIPTION

Set the origin of the pixelmap for all read and write operations to a device interface using the PixelmapRead and PixelmapWrite drawing functions. The default origin is 0,0.

Get xorig and yorig as output arguments using 

         void vgl_PixelmapGetOrigin (vgl_Pixelmap *pixelmap,
                                     Vint *xorig,
                                     Vint *yorig)

Pixelmap

NAME

vgl_PixelmapSetSize - set size of pixelmap

C SPECIFICATION

    void vgl_PixelmapSetSize (vgl_Pixelmap *pixelmap,
                              Vint xsize,
                              Vint ysize)

INPUT ARGUMENTS

    pixelmap     Pointer to Pixelmap object.
    xsize,ysize  Horizontal and vertical size of pixelmap in device coordinates

OUTPUT ARGUMENTS

    None

ERRORS

VGL_ERROR_OPERATION is generated if the size is set after the drawing function PixelmapCreate has been called.

DESCRIPTION

Set the size of the pixelmap for all read and write operations to a device interface using the PixelmapRead and PixelmapWrite drawing functions. The default size is (0,0), this defaults to the current device size. The size must be set before the PixelmapCreate drawing function has been called. The size may be set after the PixelmapDestroy drawing function has been called.

Get xsize and ysize as output arguments using 

         void vgl_PixelmapGetSize (vgl_Pixelmap *pixelmap,
                                   Vint *xsize,
                                   Vint *ysize)