C++ Games Programming

home *** CD-ROM | disk | FTP | other *** search

/ C++ Games Programming / CPPGAMES.ISO / fgl / fglight / manuals.arj / USER09.DOC < prev next >

Wrap

Text File | 1995-02-06 | 71KB | 1,557 lines

Chapter 9 Image Files 184 Fastgraph User's Guide Overview Within the context of Fastgraph, an image is a rectangular area containing some type of picture. An image might be something as simple as a pointing hand icon, or as detailed as the dashboard of a sports car. Fastgraph includes several routines to display, retrieve, and manipulate images. In this chapter we'll begin our discussion of images by looking at the PCX, GIF, FLI/FLC, and pixel run image file formats Fastgraph supports, as well as the routines available for displaying and creating image files in these formats. PCX Files The PCX file format was originally developed by ZSoft Corporation for their commercial paint program, PC Paintbrush. It has evolved into one of the more popular image file formats because so many products can read and write PCX files to at least some extent. Fastgraph includes routines for displaying and creating PCX files, as well as other PCX support functions. The fg_showpcx routine displays an image stored in a PCX file. It can position the image using the coordinate information in the PCX header, or such that its upper left corner is at the graphics cursor position on the active video page. The first argument to fg_showpcx is the name of the PCX file (it may include a path name), and its second argument is a bit mask that controls how the image is displayed. The file name must be terminated with a null character, so BASIC, FORTRAN, and Pascal programmers will need to store a zero byte as the last character of the file name string. The fg_showpcx routine cannot display PCX images in virtual buffers. A separate routine, fg_loadpcx, is provided for this purpose and will be described later in this section. In the current version of Fastgraph, only the low-order three bits (bits 0 to 2) of the bit mask argument are meaningful. The following table summarizes the meanings of these bits. Bit Value Meaning 0 0 Use palette values stored in the PCX file 0 1 Use the current palette settings 1 0 Display image at position indicated in PCX header 1 1 Display image at current graphics position 2 0 Display image data from the PCX file 2 1 Display image data from the fg_imagebuf buffer All other bits are reserved and should be zero to guarantee compatibility with future releases. The fg_showpcx routine returns a value of 0 if successful, 1 if the specified file wasn't found, and 2 if the file is not a PCX file. The fg_makepcx routine creates a PCX file from the specified rectangular region of the active video page or virtual buffer. Its first four arguments define the minimum x, maximum x, minimum y, and maximum y screen space coordinates of the region (the minimum x coordinate is reduced to a byte boundary if necessary). Its fifth argument is the name of the PCX file to create (it may include a path name). As with fg_showpcx, the file name must be terminated with a null character. If an identically named file exists, it is Chapter 9: Image Files 185 overwritten. The fg_makepcx routine returns a value of 0 if successful, and 1 if the PCX file was not created. Example 9-1 uses fg_showpcx and fg_makepcx to create a new PCX file from selected rows of an existing 256-color 320x200 PCX file. As written, the program uses the file CORAL.PCX to create NEW.PCX, but it could easily be extended to work with any PCX files. The call to fg_showpcx displays the image in CORAL.PCX using the screen position and palette settings defined in the PCX file. After waiting for a keystroke, the program calls fg_makepcx to create a PCX file named NEW.PCX from pixel rows 80 through 99 of the original image. In case the program encounters any problems, it prints an error message before exiting. Example 9-1. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int old_mode; int read_status, write_status; fg_initpm(); if (fg_testmode(19,1) == 0) { printf("This program requires a 320 "); printf("x 200 MCGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(19); read_status = fg_showpcx("CORAL.PCX",0); fg_waitkey(); if (read_status == 0) write_status = fg_makepcx(0,319,80,99,"NEW.PCX"); else write_status = 1; fg_setmode(old_mode); fg_reset(); if (read_status == 1) printf("CORAL.PCX not found.\n"); else if (read_status == 2) printf("CORAL.PCX is not a PCX file.\n"); if (write_status == 1) printf("NEW.PCX not created.\n"); } In the Tandy/PCjr 16-color graphics mode (mode 9) and the native EGA graphics modes (modes 13 through 16), the palette registers are not readable. Hence, fg_makepcx will use the default palette settings when used in these 186 Fastgraph User's Guide video modes on Tandy and EGA systems. Displaying a PCX file at a lower resolution (for example, a 640x480 PCX file at 320x200) will truncate the display on the right and on the bottom. This effectively displays the upper left corner of the image. The fg_showpcx and fg_makepcx routines have no effect in text video modes or in the Hercules low-resolution graphics mode. If you want to display a PCX file in a virtual buffer, you must use Fastgraph's fg_loadpcx routine instead of fg_showpcx. The fg_loadpcx parameters and return values are identical to those of fg_showpcx, but the image destination is a virtual buffer and not video memory. We found it preferable to create a separate function for loading PCX images into virtual buffers because PCX files closely resemble the structure of video memory. The fg_showpcx routine is optimized to take advantage of this, while fg_loadpcx must perform the additional task of converting the pixel data to the virtual buffer format. Example 9-2 shows how to display a PCX image in a virtual buffer with fg_loadpcx. The CORAL.PCX file used in this example is a 320x200 image, so the required virtual buffer size is 64,000 bytes. After creating and opening the virtual buffer, the program calls fg_loadpcx to display the image in the virtual buffer. If successful, it makes the image visible by copying the virtual buffer contents to the visual page using fg_vbpaste. Example 9-2. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> #ifdef __TURBOC__ #include <alloc.h> #else #include <malloc.h> #endif void main(void); void main() { int handle; int old_mode; int status; #ifdef FG32 char *buffer; #else char huge *buffer; #endif fg_initpm(); if (fg_testmode(19,1) == 0) { printf("This program requires a 320 "); printf("x 200 MCGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(19); fg_vbinit(); Chapter 9: Image Files 187 #ifdef FG32 buffer = (char *)malloc(64000); #elif defined(__TURBOC__) buffer = (char huge *)farmalloc(64000L); #else buffer = (char huge *)halloc(64000L,1); #endif if (buffer == NULL) { fg_setmode(old_mode); fg_reset(); printf("Could not create the virtual buffer.\n"); exit(1); } handle = fg_vbdefine(buffer,320,200); fg_vbopen(handle); status = fg_loadpcx("CORAL.PCX",0); if (status == 0) { fg_vbpaste(0,319,0,199,0,199); fg_waitkey(); } fg_vbclose(); fg_setmode(old_mode); fg_reset(); if (status == 1) printf("CORAL.PCX not found.\n"); else if (status == 2) printf("CORAL.PCX is not a PCX file.\n"); } Because their structure parallels that of video memory, PCX files are specific to certain video modes. If you try to display a PCX file in an incompatible video mode, fg_showpcx will still display something, but it will be garbled. The following table summarizes the compatible video modes for PCX files. If PCX file was You can display created in mode it in these modes 4, 5 4, 5 6, 11 6, 11, 13-18, 28, 29 9 9 13-18 13-18, 28, 29 19-27 19-27 28-29 13-18, 28, 29 Unlike fg_showpcx, fg_loadpcx does not display a PCX image directly to video memory. The fg_loadpcx routine instead converts the mode-specific structure of the PCX file to the mode-independent virtual buffer format as it unpacks the image data. This overhead means fg_showpcx is faster than fg_loadpcx, but fg_loadpcx makes it possible to display any PCX file in any graphics video mode. The only problem occurs when displaying a PCX image with more colors than the current video mode supports (for example, displaying a 188 Fastgraph User's Guide 256-color PCX in a 16-color mode). In this case, fg_vbpaste will display pixels of color c in color c modulo n, where n is the number of colors available in the current video mode. The fg_pcxpal routine retrieves the palette of an image stored in a PCX file. Its first argument is a PCX file name, terminated by a zero byte as with fg_showpcx. Its second argument is the address of the array that will receive the PCX palette values. The palette values are returned as RGB color components, each between 0 and 63. The first three bytes of this array will contain the RGB values for color 0, the next three for color 1, and so forth. The array size in bytes must be at least three times the number of colors in the PCX image. If successful, the fg_pcxpal function return value is the number of colors in the PCX palette, either 16 or 256. The possible error return values are -1 (file not found) and -2 (file is not a PCX file). For video modes 18 and above, the fg_pcxpal palette values are suitable for use with fg_setdacs. For the native EGA graphics modes (13 to 16), the palette values must be converted into mode-specific values (with fg_maprgb) before being used with fg_palette or fg_palettes. If the PCX file includes an extended (256-color) palette, fg_pcxpal will return the values in the extended palette. Otherwise, it will return the values from the 16-color palette in the PCX header. Fastgraph's fg_pcxmode function determines the optimal video mode for displaying a PCX file. By optimal, we mean the compatible video mode having the lowest resolution larger than or equal to the image dimensions. The fg_pcxmode routine has a single argument -- the address of a buffer that contains a 128-byte PCX file header. Specific values defined in certain fields of the PCX header determine which video mode is optimal. A positive return value from fg_pcxmode represents the optimal video mode number. The possible error returns are -1 if the buffer does not contain a valid PCX header, and -2 if fg_pcxmode cannot find any compatible video mode. Another useful PCX support function is fg_pcxrange, which returns the image position information from the PCX header. The first fg_pcxrange argument is the address of a buffer containing a 128-byte PCX file header. The remaining four arguments receive the minimum x, maximum x, minimum y, and maximum y values of the corresponding PCX image. You can use the image extents to determine the image dimensions -- for example, the width of a PCX image would be maximum_x - minimum_x + 1. How do we get the header from a PCX file into the buffer passed to fg_pcxmode or fg_pcxrange? The easiest way is with the fg_pcxhead function. Its first argument is the name of the PCX file from which to retrieve the header (as before, the file name must be null-terminated). The second argument is the address of the buffer that will receive the PCX header. The size of this buffer must be at least 128 bytes. If successful, fg_pcxhead returns zero. Otherwise, the return value is -1 if the specified file could not be opened, or -2 if the file is not a PCX file. After successfully reading the PCX header, you can pass it to fg_pcxmode to determine the optimal video mode for the PCX file. Full information about the 128-byte PCX file header appears in Appendix H. Example 9-3 uses Fastgraph's fg_pcxhead, fg_pcxmode, fg_pcxpal, and fg_pcxrange routines to obtain information about the CORAL.PCX file. It Chapter 9: Image Files 189 displays the optimal video mode number for displaying the image, the image dimensions, and the image's first 16 color palette values. Example 9-3. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int i, j; int mode, status; int minx, maxx, miny, maxy; unsigned char PCXpal[768]; unsigned char header[128]; fg_initpm(); status = fg_pcxhead("CORAL.PCX",header); if (status == -1) { printf("Can't open CORAL.PCX.\n"); exit(1); } else if (status == -2) { printf("CORAL.PCX is not a PCX file.\n"); exit(1); } mode = fg_pcxmode(header); printf("Optimal display mode is %d.\n",mode); fg_pcxrange(header,&minx,&maxx,&miny,&maxy); printf("Image size is %d by %d pixels.\n",maxx-minx+1,maxy-miny+1); fg_pcxpal("CORAL.PCX",PCXpal); printf("First 16 palette values are:\n"); j = 0; for (i = 0; i < 16; i++) { printf(" color %2d: R=%2d G=%2d B=%2d\n", i,PCXpal[j],PCXpal[j+1],PCXpal[j+2]); j += 3; } } GIF Files The GIF file format was created by CompuServe, Inc., as a transmission format for images and graphics data across the CompuServe network. It has evolved into what is probably the most popular image file format in use today. GIF files are especially prevalent on bulletin boards and electronic data networks because their efficient image compression results in less storage space and faster transmission times than other image file formats. GIF, pronounced "jif", is an acronym for Graphics Interchange Format. The format is 190 Fastgraph User's Guide the copyright property of CompuServe, Inc., whose GIF specification "grants a limited, non-exclusive, royalty-free license for the use of the Graphics Interchange Format in computer software; computer software utilizing GIF must acknowledge ownership of the Graphics Interchange Format and its Service Mark by CompuServe, Inc., in user and technical documentation". Two GIF specifications, released in 1987 and 1989, are defined. The 1989 specification (known as "89a") is a superset of the original 1987 specification (known as "87a"). Fastgraph's GIF file display routine can handle either 87a or 89a files. For maximum portability, the GIF file creation routine always produces files conforming to the 87a specification. The fg_showgif routine displays an image stored in a GIF file. It can position the image using the coordinate information in the GIF header, or such that its upper left corner is at the graphics cursor position on the active video page or virtual buffer. The fg_showgif arguments are the same as for fg_showpcx, except the file name must of course reference a GIF file rather than a PCX file. Likewise, the fg_showgif return values are analogous to those of fg_showpcx. The fg_makegif routine creates a GIF file from the specified rectangular region of the active video page or virtual buffer. Its arguments and return value are analogous to those of fg_makepcx. Example 9-4 uses fg_showgif and fg_makegif to create a new GIF file from selected rows of an existing 256-color 320x200 GIF file. Similar to example 9-1, the program uses the file CORAL.GIF to create NEW.GIF, but it could easily be extended to work with any GIF files. The call to fg_showgif displays the image in CORAL.GIF using the screen position and palette settings defined in the GIF file. After waiting for a keystroke, the program calls fg_makegif to create a GIF file named NEW.GIF from pixel rows 80 through 99 of the original image. In case the program encounters any problems, it prints an error message before exiting. Example 9-4. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int old_mode; int read_status, write_status; fg_initpm(); if (fg_testmode(19,1) == 0) { printf("This program requires a 320 "); printf("x 200 MCGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(19); read_status = fg_showgif("CORAL.GIF",0); Chapter 9: Image Files 191 fg_waitkey(); if (read_status == 0) write_status = fg_makegif(0,319,80,99,"NEW.GIF"); else write_status = 1; fg_setmode(old_mode); fg_reset(); if (read_status == 1) printf("CORAL.GIF not found.\n"); else if (read_status == 2) printf("CORAL.GIF is not a GIF file.\n"); if (write_status == 1) printf("NEW.GIF not created.\n"); } Like fg_makepcx, the fg_makegif routine will use the default palette settings when running on Tandy and EGA systems. Displaying a GIF file at a lower resolution (for example, a 640x480 GIF file at 320x200) will truncate the display on the right and on the bottom. This effectively displays the upper left corner of the image. Unlike PCX files, GIF files do not exhibit compatibility problems between 16-color and 256-color graphics modes. When fg_showgif displays a 256-color GIF in a 16-color mode, it displays pixels of color c in color c modulo 16. The fg_showgif and fg_makegif routines have no effect in text video modes, or in CGA and Hercules graphics modes. Fastgraph includes additional GIF support routines analogous to those for PCX files. The fg_gifpal routine retrieves the palette of an image stored in a GIF file. If the GIF file includes a local palette for the first image, fg_gifpal will return the values from the local palette. Otherwise, fg_gifpal will return the values from the GIF file's global palette. The fg_gifmode function determines the optimal video mode for displaying a GIF file. The fg_gifrange routine returns the image position information from the GIF header. The fg_gifhead routine reads a GIF file's global header and first local header into a 23-byte array (full information about the headers appears in Appendix H). The parameters and return values for these routines are the same as for their PCX counterparts. Example 9-5 uses Fastgraph's fg_gifhead, fg_gifmode, fg_gifpal, and fg_gifrange routines to obtain information about the CORAL.GIF file. It displays the optimal video mode number for displaying the image, the image dimensions, and the image's first 16 palette values. Example 9-5. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int i, j; int mode, status; 192 Fastgraph User's Guide int minx, maxx, miny, maxy; unsigned char GIFpal[768]; unsigned char header[23]; fg_initpm(); status = fg_gifhead("CORAL.GIF",header); if (status == -1) { printf("Can't open CORAL.GIF.\n"); exit(1); } else if (status == -2) { printf("CORAL.GIF is not a GIF file.\n"); exit(1); } mode = fg_gifmode(header); printf("Optimal display mode is %d.\n",mode); fg_gifrange(header,&minx,&maxx,&miny,&maxy); printf("Image size is %d by %d pixels.\n",maxx-minx+1,maxy-miny+1); fg_gifpal("CORAL.GIF",GIFpal); printf("First 16 palette values are:\n"); j = 0; for (i = 0; i < 16; i++) { printf(" color %2d: R=%2d G=%2d B=%2d\n", i,GIFpal[j],GIFpal[j+1],GIFpal[j+2]); j += 3; } } FLI and FLC files FLI and FLC files (collectively called flic files) contain sequences of image frames that can be displayed in rapid succession to achieve the illusion of movement (this is called playing a flic file). FLI files are produced by Autodesk Animator and always have a 320x200 resolution, while FLC files are produced by Autodesk Animator Pro and can have any resolution. Fastgraph's flic file routines work with both FLI and FLC files, but they are restricted to 256-color graphics modes because flic files always contain 256-color images. The first frame of a flic file is usually a compressed version of the entire image, while later frames are compressed versions of the differences between that frame and the previous frame. This compression scheme is often called delta compression in flic file literature. Fastgraph includes both high-level and low-level routines for working with flic files. The most important high-level routine, fg_showflic, plays the entire contents of a flic file any number of times. It can position the image such that its upper left corner is at the screen origin or at the graphics cursor position on the active video page (flic files cannot be played in virtual buffers). The fg_showflic routine expects three arguments. The first is the flic file name, which may include a path name, but must be null- terminated. The second specifies the number of times to play the flic file. If the play count is zero, fg_showflic will play it continuously. The fg_showflic Chapter 9: Image Files 193 routine will stop playing the flic file if the Escape key is pressed. Note that this is the only way to stop playing the flic file if the play count is zero (continuous play). The third fg_showflic argument is a bit mask that controls how the image is displayed. In the current version of Fastgraph, only the low-order three bits (bits 0 to 2) of the bit mask argument are meaningful. The following table summarizes the meanings of these bits. Bit Value Meaning 0 0 Delay between frames as indicated in flic header 0 1 No delay between frames 1 0 Display image relative to screen origin 1 1 Display image relative to current graphics position 2 0 Display image data from the specified flic file 2 1 Display image data from the fg_imagebuf buffer All other bits are reserved and should be zero to guarantee compatibility with future releases. The fg_showflic routine returns a value of 0 if successful, 1 if the specified file wasn't found, and 2 if the file is not a flic file. Example 9-6 is a simple flic file player. It uses the standard VGA/MCGA 256-color graphics mode (mode 19) to play the flic file GLASS.FLI, one of the examples supplied with Autodesk Animator. The upper left corner of the flic file will be at the screen origin, with a delay between frames as defined in the flic file header. Example 9-6. #include <fastgraf.h> #include <stdio.h> void main(void); void main(void) { int status; fg_initpm(); fg_setmode(19); status = fg_showflic("GLASS.FLI",1,0); if (status == 0) fg_waitkey(); fg_setmode(3); fg_reset(); if (status == 1) printf("GLASS.FLI not found.\n"); else if (status == 2) printf("GLASS.FLI is not an FLI or FLC file.\n"); } Fastgraph includes additional flic support routines similar to those for PCX and GIF files. The fg_flichead routine reads the specified flic file's 194 Fastgraph User's Guide 128-byte header (full information about the header appears in Appendix H). The fg_flicmode function determines the optimal video mode for playing a flic file. Its only argument is a 128-byte array containing a flic file header returned by fg_flichead. If successful, it returns the optimal video mode number for playing the flic image. If the array does not contain a valid flic file header, fg_flicmode returns -1. The fg_flicsize routine returns the image dimensions from the flic header. Its first argument is a 128-byte flic header array, and is remaining two arguments receive the image width and height in pixels. Example 9-7 uses these three routines to obtain information about the GLASS.FLI file. It displays the optimal video mode number for playing the flic file, as well as the image dimensions. Example 9-7. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int mode, status; int width, height; unsigned char header[128]; fg_initpm(); status = fg_flichead("GLASS.FLI",header); if (status == -1) { printf("Can't open GLASS.FLI.\n"); exit(1); } else if (status == -2) { printf("GLASS.FLI is not a FLI or FLC file.\n"); exit(1); } mode = fg_flicmode(header); printf("Optimal display mode is %d.\n",mode); fg_flicsize(header,&width,&height); printf("Image size is %d by %d pixels.\n",width,height); } Fastgraph's low-level flic routines provide the ability to display flic files one frame at a time. This is desirable when your program must perform other tasks between frames, or for playing two or more flic files at the same time. To use Fastgraph's low-level flic routines, call fg_flicopen for each flic file. The first fg_flicopen argument is the flic file name. The second argument is a 16-byte array that will receive a context descriptor for the flic file. You must create a context descriptor with fg_flicopen for each flic file you'll access with the low-level flic file routines (the number of flic files you can have open at any one time is limited by the FILES specifier in your CONFIG.SYS file). The context descriptor is then passed to other routines when accessing the flic file. If successful, fg_flicopen fills the context descriptor, positions the flic file at the first frame, and returns zero. The Chapter 9: Image Files 195 possible error return values are -1 (file not found) and -2 (file is not an FLI or FLC file). The fg_flicplay routine plays one or more frames from a flic file and leaves the file positioned at the beginning of the next frame. Its three arguments are the same as for fg_showflic except the first argument is a context descriptor instead of a flic file name. The fg_flicskip routine advances over flic file frames. Its first argument is the flic file's context descriptor, and its second argument is the number of frames to skip (if the frame count is negative, the file position is reset to the first frame). Both routines return the number of frames played, which may be less than the number of frames requested if the end-of-file is reached. Fastgraph's last low-level flic routine, fg_flicdone, closes a flic file previously opened with fg_flicopen. Its only argument is the flic file's context descriptor. Example 9-8 is similar to example 9-6, but it plays the GLASS.FLI file one frame at a time using Fastgraph's low-level flic routines. It opens the flic file with fg_flicopen, which returns a 16-byte context descriptor for the file. If the file was opened successfully, the program plays each frame by calling fg_flicplay in a loop, waiting for a keystroke between each frame (note that the bit mask passed to fg_flicplay has bit 0 set, as it's usually not too meaningful to delay between frames when playing frames individually). Eventually we'll reach the end-of-file, indicated by an fg_flicplay return value of zero. When this occurs, the program calls fg_flicdone and exits. Example 9-8. #include <fastgraf.h> #include <stdio.h> void main(void); void main(void) { int frames; int status; char context[16]; fg_initpm(); fg_setmode(19); status = fg_flicopen("GLASS.FLI",context); if (status == 0) { do { frames = fg_flicplay(context,1,1); fg_waitkey(); } while (frames > 0); fg_flicdone(context); } fg_setmode(3); fg_reset(); if (status == -1) printf("GLASS.FLI not found.\n"); else if (status == -2) 196 Fastgraph User's Guide printf("GLASS.FLI is not an FLI or FLC file.\n"); } Pixel Run Files Fastgraph also provides its own mode-independent image file format called pixel run format. Pixel run files are useful in programs that must run in different video modes (but with the same resolution) because you can use the same image files for two-color modes as for 256-color modes. Two variations of the pixel run format exist -- standard pixel run files (SPR files) and packed pixel run files (PPR files). The packed pixel run format does not support 256- color images but will produce a smaller file if the image has 16 colors or less. Pixel run files do not include a header or any color palette information. The best way to illustrate the pixel run file format is with an example. Suppose we want to display a small triangle whose perimeter is a different color than its interior. To create the standard pixel run equivalent of this image, we must inscribe the triangle in a rectangular area. Hence, the pixel representation of our triangle might appear as shown here: . . . . * . . . . . . . * x * . . . . . * x x x * . . . * x x x x x * . * * * * * * * * * As shown in this diagram, our triangle image is nine pixels wide at its base and five pixels high. The pixels indicated by an asterisk (*) are the triangle's perimeter, while those indicated by an x represent its interior points. The pixels shown as periods (.) are not part of the triangle itself, but they are part of the image. In this example, we can treat them as background pixels. If we start at the lower left corner of the image and proceed to the right, we could represent the first row of the image as nine pixels of color "asterisk". Such a group of consecutive identically colored pixels is called a pixel run, so a single pixel run describes the first row of the image. The row above this one is a bit more complex. It consists of five pixel runs: one pixel of color "period", followed by one of color "asterisk", then five of color "x", one of color "asterisk", and finally one of color "period". While we could construct separate pixel runs for each row of the image, notice that three of the five rows in our triangle begin with the same color pixel as the rightmost pixel in the previous row. Fastgraph's pixel run formats let you take advantage of this property by allowing pixel runs to wrap from one row to the next. This means we can represent the pixel run of color "period" extending from the right side of the second row to the left side of the third row as a single run of three pixels. An standard pixel run (SPR) file is nothing more than such a sequence of (color,count) pairs, as shown in the following diagram. Chapter 9: Image Files 197 byte 0 color for run 1 1 count for run 1 2 color for run 2 3 count for run 2 2n-2 color for run n 2n-1 count for run n Each color is a value between 0 and 255 specifying the color index for that pixel run. Each count is a value between 0 and 255 specifying the length in pixels of that pixel run. If a single run exceeds 255 pixels, it must be broken into two or more runs. For example, we could represent a pixel run of length 265 as a run of length 255 followed by a run of length 10 of the same color. Note that the space in bytes needed to store an SPR image is twice the number of runs. Fastgraph's fg_showspr routine displays an SPR file. Its first argument is the name of the file containing the image (it may include a path name). The file name must be terminated with a null character, so BASIC, FORTRAN, and Pascal programmers will need to store a zero byte as the last character of the file name string. The second argument is the width in pixels of the image. The fg_showspr routine displays the image such that its lower left corner is at the graphics cursor position. The possible return values for fg_showspr are success (0) and file not found (1). To create an SPR file, use the fg_makespr routine. Its arguments and return values are the same as for fg_makepcx and fg_makegif. Example 9-9 uses fg_showspr and fg_makespr to create a new SPR file from selected rows of an existing 16-color 320x200 SPR file. Similar to examples 9-1 and 9-4, the program uses the file CORAL.SPR to create NEW.SPR, but it could easily be extended to work with any SPR files. The call to fg_move to establishes the lower left corner of the screen as the graphics cursor position (contrast this with the upper left corner being the reference point for PCX, GIF, and flic files). Then program then calls fg_showspr to display the image. After waiting for a keystroke, the program calls fg_makespr to create an SPR file named NEW.SPR from pixel rows 80 through 99 of the original image. In case the program encounters any problems, it prints an error message before exiting. Example 9-9. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() 198 Fastgraph User's Guide { int new_mode, old_mode; int read_status, write_status; fg_initpm(); new_mode = fg_bestmode(320,200,1); if (new_mode < 0 || new_mode == 12) { printf("This program requires a 320 "); printf("x 200 color graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(new_mode); fg_move(0,199); read_status = fg_showspr("CORAL.SPR",320); fg_waitkey(); if (read_status == 0) write_status = fg_makespr(0,319,80,99,"NEW.SPR"); else write_status = 1; fg_setmode(old_mode); fg_reset(); if (read_status == 1) printf("CORAL.SPR not found.\n"); if (write_status == 1) printf("NEW.SPR not created.\n"); } If you have an image that only uses the first 16 color indices (0 to 15), you can use Fastgraph's packed pixel run (PPR) image format. This format packs two color values into each color byte, so it takes three bytes instead of four to represent two pixel runs. This means a PPR file is 25% smaller than its SPR equivalent. In each set of three bytes, the high four bits of the first byte contain the color of the first run, and the low four bits contain the color of the second run. The second byte contains the length of the first run, and the third byte contains the length of the second run. The following diagram illustrates the structure of the packed pixel file. In this example, the file is assumed to contain n pixel runs, where n is an even number. If n is odd, the byte offset for the last element is 3n/2 (truncated) instead of 3n/2-1, and the low four bits of the last color byte (that is, the color for pixel run n+1) are ignored. 7 4 3 0 byte 0 color for run 1 color for run 2 1 count for run 1 2 count for run 2 3 color for run 3 color for run 4 Chapter 9: Image Files 199 4 count for run 3 5 count for run 4 3n/2-3 color for run n-1 color for run n 3n/2-2 count for run n-1 3n/2-1 count for run n The structure of the PPR file allows for color values between 0 and 15, and run lengths between 0 and 255. The space in bytes needed to store an image in PPR format is 1.5 times the number of runs, compared to twice the number of runs for the SPR format. The fg_showppr and fg_makeppr routines display and create PPR files, respectively. Their arguments and return values are the same as those of fg_showspr and fg_makespr. If we wanted to display PPR files instead of SPR files in example 9-9, all that's necessary is changing the fg_showspr and fg_makespr calls to fg_showppr and fg_makeppr. Fastgraph's fg_dispfile routine displays both SPR and PPR files. The first of its three arguments is the name of the image file (it may include a path name). The file name must be terminated with a null character, so BASIC, FORTRAN, and Pascal programmers will need to store a zero byte as the last character of the file name string. The second argument is the image width in pixels, and the third argument defines the image format (that is, SPR or PPR). As with other pixel run display routines, fg_dispfile displays the image such that its lower left corner is at the graphics cursor position. Example 9-10 illustrates how to use fg_dispfile to display an image stored in a pixel run file. The program displays two identical images, one in an SPR file and the other in a PPR file. Each image is a picture of the sea floor and some coral, as might be used for the background in an aquarium. The program runs in a 320x200 graphics mode, and the images fill the entire screen. The SPR image is in file CORAL.SPR. The program uses fg_move to establish the lower left corner of the screen as the graphics cursor position and then calls fg_dispfile to display the image. The value of fg_dispfile's third argument tells Fastgraph the image format. A value of 0 indicates the file contains an image in SPR format, while a value of 1 indicates an image in PPR format. As mentioned earlier, the image fills the entire screen, so its width is 320 pixels. After waiting for a keystroke, the program clears the previous image from the screen and then calls fg_dispfile to display the PPR image from the file CORAL.PPR. The program leaves the second image on the screen until another keypress, at which time it restores the original video mode and screen attributes and returns to DOS. 200 Fastgraph User's Guide Example 9-10. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); void main() { int old_mode, new_mode; fg_initpm(); new_mode = fg_bestmode(320,200,1); if (new_mode < 0 || new_mode == 12) { printf("This program requires a 320 "); printf("x 200 color graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(new_mode); fg_move(0,199); fg_dispfile("CORAL.SPR",320,0); fg_waitkey(); fg_erase(); fg_dispfile("CORAL.PPR",320,1); fg_waitkey(); fg_setmode(old_mode); fg_reset(); } The SNAPSHOT utility distributed with Fastgraph is a terminate and stay resident program (TSR) that can capture graphics mode screen images and save them in SPR files. Thus, you can easily create files with SNAPSHOT and display them with fg_showspr or fg_dispfile. Another TSR utility, GrabRGB, is useful for capturing RGB color values from 256-color images. Appendix A contains complete descriptions of the SNAPSHOT and GrabRGB utilities. Display Patterns Example 9-10 works well in the graphics video modes with 16 or 256 available colors. However, in the four-color CGA graphics modes the resulting image is not too good because of our limited color choices, and it would look even worse in the Hercules graphics mode. The Fastgraph routine fg_pattern allows you to associate a dither pattern (actually, any pixel sequence) with one of Fastgraph's 256 color indices appearing in a pixel run map. When displaying an SPR or PPR file, Fastgraph will use the pattern associated with that color index instead of displaying the color itself. Chapter 9: Image Files 201 The fg_pattern routine requires two integer arguments -- a color index (between 0 and 255) and the display pattern defined for that color index. A display pattern's structure resembles the structure of video memory and is thus dependent on the current video mode. The following sections list the initial display patterns and explain how to construct new display patterns for different graphics video modes. CGA four-color graphics modes In the four-color CGA graphics modes (modes 4 and 5), the display pattern consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each pixel assumes a value between 0 and 3, so the pattern represents four pixels. In even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd- numbered pixel rows, Fastgraph rotates the original pattern to the left by the number of bits specified by the shift count. For example, if we are using the default CGA color palette, we could create a darker shade of cyan by alternating cyan pixels (color 1, 01 binary) with white pixels (color 3, 11 binary), as shown here: 01 11 01 11 If we convert this pixel pattern to its hexadecimal equivalent, we get the value 77. To complete the display pattern, we need to determine the shift count. If we use a shift count of zero, the resulting display will simply be a series of cyan and white vertical lines. What we really need is a checkerboard effect where a white pixel is above and below each cyan pixel, and vice versa. If we rotate the pattern one pixel (two bits) to the left, we will achieve the desired effect. That is, a shift count of two produces the following pixel patterns: even-numbered rows 01 11 01 11 odd-numbered rows 11 01 11 01 Combining the shift count with the pixel pattern yields the display pattern 0277 hex. The shift count is normally a multiple of two; note that a zero shift count results in the same pattern being applied to all pixel rows. For the CGA four-color graphics modes, fg_setmode establishes the following initial display patterns: color shift count hexadecimal index and pattern equivalent 0 0 00000000 0000 1 0 01010101 0055 2 0 10101010 00AA 3 0 11111111 00FF These values are repeated as necessary to define color indices 4 to 255. That is, colors 4, 8, 12, ... , 252 use the same defaults as color 0. Colors 5, 9, 13, ... , 253 use the same defaults as color 1, and so forth. Also note that 202 Fastgraph User's Guide pattern 0000 represents four pixels of color 0, 0055 represents four pixels of color 1, 00AA represents four pixels of color 2, and 00FF represents four pixels of color 3. CGA two-color graphics mode In the two-color CGA graphics mode (mode 6), the display pattern also consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each pixel assumes the value 0 or 1, so the pattern represents eight pixels. In even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd- numbered pixel rows, Fastgraph rotates the original pattern to the left by the number of bits specified by the shift count. For example, we could create a lighter shade of white by alternating black pixels (color 0) with white pixels (color 1), as shown here: 0 1 0 1 0 1 0 1 If we convert this pixel pattern to its hexadecimal equivalent, we get the value 55. To complete the display pattern, we need to determine the shift count. We must rotate the pattern one pixel (one bit) to the left to achieve the checkerboard effect as in the CGA four color graphics modes. That is, a shift count of one produces the following pixel patterns: even-numbered rows 0 1 0 1 0 1 0 1 odd-numbered rows 1 0 1 0 1 0 1 0 Combining the shift count with the pixel pattern yields the display pattern 0155 hex. For the CGA two-color graphics mode, fg_setmode establishes the initial display patterns such that all even-numbered color indices are assigned the value 0000, while all odd-numbered color indices are assigned the value 00FF. Note that pattern 0000 represents eight pixels of color 0, and 00FF represents eight pixels of color 1. Tandy/PCjr 16-color graphics mode In the Tandy/PCjr 16-color graphics mode (mode 9), the display pattern also consists of an 8-bit shift count followed by an 8-bit pixel pattern. Each pixel assumes a value between 0 and 15, so the pattern represents two pixels. In even-numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd- numbered pixel rows, Fastgraph rotates the original pattern to the left by the number of bits specified by the shift count. For example, we could create a lighter shade of blue by alternating blue pixels (color 1, 0001 binary) with white pixels (color 15, 1111 binary), as shown here: 0001 1111 Chapter 9: Image Files 203 If we convert this pixel pattern to its hexadecimal equivalent, we get the value 1F. To complete the display pattern, we need to determine the shift count. Using the same process as in the CGA graphics modes, we must rotate the pattern one pixel (four bits) to the left to achieve the checkerboard effect. That is, a shift count of four produces the following pixel patterns: even-numbered rows 0001 1111 odd-numbered rows 1111 0001 Combining the shift count with the pixel pattern yields the display pattern 041F hex. The shift count is normally zero or four; note that a zero shift count results in the same pattern being applied to all pixel rows. For the Tandy/PCjr 16-color graphics modes, fg_setmode establishes the initial display patterns such that color 0 is assigned the value 0000 (two pixels of color 0), color 1 is assigned the value 0011 (two pixels of color 1), color 2 is assigned the value 0022 (two pixels of color 2), and so forth. These values are repeated as necessary to define color indices 16 to 255. That is, colors 0, 16, 32, ... , 240 use the same defaults as color 0. Colors 1, 17, 33, ... , 241 use the same defaults as color 1, and so forth. Hercules graphics modes The structure of the display patterns for the Hercules graphics modes (modes 11 and 12) is the same as two of the CGA graphics modes. For the standard Hercules graphics mode (mode 11), please refer to the discussion of CGA two-color (mode 6) display patterns. For the low-resolution Hercules graphics mode (mode 12), please refer to the discussion of the CGA four-color (mode 4) display patterns. EGA/VGA/SVGA 16-color graphics modes In the EGA/VGA/SVGA 16-color graphics modes (modes 13 to 16, 18, 28, and 29), the display pattern consists of two 4-bit color values (for consistency with the other video modes, we still pass the display pattern as a 16-bit or 32-bit quantity). Each pixel assumes a value between 0 and 15 (0 and 5 in the EGA monochrome graphics mode), so the pattern represents two pixels. In even- numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-numbered pixel rows, Fastgraph rotates the original pattern one pixel (four bits) to the left. For example, we could create a lighter shade of blue by alternating blue pixels (color 1, 0001 binary) with white pixels (color 15, 1111 binary), as shown here: 0001 1111 If we convert this pixel pattern to its hexadecimal equivalent, we get the value 1F. The implied four-bit shift count produces the following pixel patterns: 204 Fastgraph User's Guide even-numbered rows 0001 1111 odd-numbered rows 1111 0001 Extending the pixel pattern to a 16-bit or 32-bit quantity yields the display pattern 001F hex. For the EGA/VGA/SVGA 16-color graphics modes, fg_setmode establishes the initial display patterns such that color 0 is assigned the value 0000 (two pixels of color 0), color 1 is assigned the value 0011 (two pixels of color 1), color 2 is assigned the value 0022 (two pixels of color 2), and so forth. These values are repeated as necessary to define color indices 16 to 255. That is, colors 0, 16, 32, ... , 240 use the same defaults as color 0. Colors 1, 17, 33, ... , 241 use the same defaults as color 1, and so forth. MCGA/VGA 2-color graphics mode In the two-color MCGA/VGA graphics mode (mode 17), the display pattern consists of two 1-bit color values (for consistency with the other video modes, we still pass the display pattern as a 16-bit or 32-bit quantity). Each pixel assumes the value 0 or 1, so the pattern represents two pixels. In even- numbered pixel rows, Fastgraph uses the pixel pattern itself. In odd-numbered pixel rows, Fastgraph rotates the original pattern one pixel (one bit) to the left. For example, we could create a lighter shade of white by alternating black pixels (color 0) with white pixels (color 1), as shown here: 0 1 If we convert this pixel pattern to its hexadecimal equivalent, we get the value 01. The implied one-bit shift count produces the following pixel patterns: even-numbered rows 0 1 odd-numbered rows 1 0 Extending the pixel pattern to a 16-bit or 32-bit quantity yields the display pattern 0001 hex. For the VGA/MCGA two-color graphics mode, fg_setmode establishes the initial display patterns such that all even-numbered color indices are assigned the value 0000 (two pixels of color 0), while all odd-numbered color indices are assigned the value 0003 (11 binary, or two pixels of color 1). 256-color graphics modes The 256-color graphics modes (modes 19 through 27) offer 262,144 different colors, so dithering is seldom (if ever) required. For this reason, fg_pattern has no effect in these video modes. Chapter 9: Image Files 205 An example Example 9-11 illustrates the use of display patterns in several graphics modes. This program runs in any 320x200 color graphics mode and displays the CORAL.PPR image with one or more of the color indices redefined. If the program runs in the standard CGA four-color mode (mode 4), it redefines the first 16 display patterns using the fg_pattern routine and the values in the CGApatterns array. In the Tandy/PCjr 16-color graphics mode (mode 9) and the EGA low-resolution graphics mode (mode 13), the program redefines color index 15 to produce an alternating gray and white dither pattern. In the MCGA 256- color mode (mode 19), display patterns are not available, so the program uses fg_setrgb to define color index 15 as slightly darker shade of gray than the default for color 7. Example 9-11. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); int CGApatterns[] = { 0x0000,0x00FF,0x00FF,0x00FF, 0x02BB,0x0000,0x0222,0x0255, 0x00FF,0x00FF,0x00FF,0x0055, 0x00AA,0x00AA,0x00FF,0x0277 }; void main() { int color; int old_mode, new_mode; fg_initpm(); new_mode = fg_bestmode(320,200,1); if (new_mode < 0 || new_mode == 12) { printf("This program requires a 320 "); printf("x 200 color graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(new_mode); if (new_mode == 4) { fg_palette(0,0); for (color = 0; color < 16; color++) fg_pattern(color,CGApatterns[color]); } else if (new_mode == 9 || new_mode == 13) fg_pattern(15,0x04F7); else fg_setrgb(15,38,38,38); fg_move(0,199); fg_showppr("CORAL.PPR",320); 206 Fastgraph User's Guide fg_waitkey(); fg_setmode(old_mode); fg_reset(); } Controlling the Image Buffer Size By default, all of Fastgraph's image file display and creation routines use an internal 4,096-byte buffer. This buffer provides an intermediate storage area, making it possible to perform more efficient buffered I/O when reading or writing the image files. The fg_imagebuf routine lets you define your own buffer for this purpose (the buffer size is limited to 64K bytes in real mode and 16-bit protected mode). Larger buffers generally make image display and creation faster. This is especially true in protected mode and when playing flic files. Calling fg_setmode resets the fg_imagebuf buffer to its default 4K size. The fg_imagebuf routine does not allocate storage for the internal buffer. Rather, it just defines the array or dynamically allocated memory block to be used as the buffer. The first argument passed to fg_imagebuf is the address of this array or memory block, and the second argument is the internal buffer size in bytes, represented as an unsigned integer. In 32-bit modes, the address is passed as an ordinary near pointer, while in 16-bit modes it is passed as a far (segmented) pointer. Fastgraph uses a far pointer in 16-bit modes to avoid wasting valuable space in the default data segment, and it almost always results in the ability to use a larger buffer. In real mode Pascal programs, the space for the internal buffer must be allocated dynamically with the GetMem procedure because it provides the only way to pass something by far reference in Pascal. Protected mode Pascal programs can use either GetMem or the GlobalAllocPtr function to allocate the buffer memory. BASIC programs must pass the image buffer as a fixed-length string. Example 9-12 shows how to use fg_imagebuf to define a larger buffer when displaying the CORAL.PCX file. In this example, we'll use a 20,000-byte static array as the image buffer. This size was chosen because it's larger than the PCX file size, so fg_showpcx can read the entire PCX file in one pass. Example 9-12. #include <fastgraf.h> #include <stdio.h> #include <stdlib.h> void main(void); #ifdef FG32 char buffer[20000]; #else char far buffer[20000]; #endif void main() { int old_mode; Chapter 9: Image Files 207 fg_initpm(); if (fg_testmode(19,1) == 0) { printf("This program requires a 320 "); printf("x 200 MCGA graphics mode.\n"); exit(1); } old_mode = fg_getmode(); fg_setmode(19); fg_imagebuf(buffer,20000); fg_showpcx("CORAL.PCX",0); fg_waitkey(); fg_setmode(old_mode); fg_reset(); } You don't need to create separate buffers for each image you display or create. Once you define an internal image buffer with fg_imagebuf, Fastgraph will use that buffer until your program exits, or until you call fg_imagebuf with a buffer size equal to zero. It's also possible to display PCX, GIF, and FLI/FLC images directly from the buffer pointed to by fg_imagebuf. This can be quite useful, for instance, when we need to display the same image file several times because we only read the file from disk once. To do this, set bit 2 of the flags parameter when using Fastgraph's PCX, GIF, or FLI/FLC image display routines. This tells Fastgraph to retrieve the image data from the fg_imagebuf buffer rather than from the file itself. In protected mode applications, using this method usually provides better performance, especially when displaying FLI or FLC files. Example 9-13 shows how to display a PCX image stored in the fg_imagebuf buffer. Example 9-13. #include <fastgraf.h> #include <io.h> #include <stdio.h> #include <stdlib.h> void main(void); #ifdef FG32 char buffer[20000]; #else char far buffer[20000]; #endif void main() { int file_size; int old_mode; FILE *stream; fg_initpm(); if (fg_testmode(19,1) == 0) { 208 Fastgraph User's Guide printf("This program requires a 320 "); printf("x 200 MCGA graphics mode.\n"); exit(1); } stream = fopen("CORAL.PCX","rb"); file_size = (int)(filelength(fileno(stream))); fread(buffer,1,file_size,stream); fclose(stream); old_mode = fg_getmode(); fg_setmode(19); fg_imagebuf(buffer,file_size); fg_showpcx("",4); fg_waitkey(); fg_setmode(old_mode); fg_reset(); } In example 9-13, we use a 20,000-byte array for the fg_imagebuf buffer. The array used with fg_imagebuf must be large enough to hold the entire image file. Note that we pass the actual file size to fg_imagebuf (in this example, we assume the file size does not exceed 20,000 bytes). It is crucial that you specify the actual file size when displaying 256-color PCX files so Fastgraph can locate the extended (256-color) palette data that might follow the image data. You must also specify the actual file size when using Fastgraph's low- level flic support routines to play flic images from the fg_imagebuf buffer. For other types of image files, we can specify either the file size or the buffer size. It's not necessary to pass a file name to the image display routines the image data resides in the fg_imagebuf buffer. In other words, the image display routines ignore the file name argument when bit 2 of the flags argument is set. However, you must still include a "place holder" argument where a file name would otherwise be expected. We recommend using the null string as in the fg_showpcx call of example 9-13, although any string can be used instead. The maximum size of the image file we can display from the fg_imagebuf buffer is of course limited to the buffer size. While this isn't in issue in 32-bit protected mode, it does impose an important restriction in real mode and 16-bit protected mode. The size of the fg_imagebuf buffer is limited to 64K bytes in 16-bit environments, meaning this feature applies only to image files that are 64K or less if you're using real mode or 16-bit protected mode. Summary of Image File Routines This section summarizes the functional descriptions of the Fastgraph routines presented in this chapter. More detailed information about these routines, including their arguments and return values, may be found in the Fastgraph Reference Manual. The image display and creation functions apply only to graphics video modes. Chapter 9: Image Files 209 FG_DISPFILE displays an image stored in a standard or packed pixel run file. The image is positioned so that its lower left corner is at the current graphics position. FG_FLICDONE closes the flic file associated with the specified context descriptor. FG_FLICHEAD reads a flic file header into a 128-byte buffer. FG_FLICMODE determines the optimal video mode for the flic image associated with the specified flic file header. The optimal mode is the 256- color graphics mode having the lowest resolution larger than or equal to the image dimensions. FG_FLICOPEN opens a flic file for subsequent processing by Fastgraph's other low-level flic file support routines. If successful, the file pointer will be positioned at the beginning of the first frame. FG_FLICPLAY displays the next one or more frames in a flic file previously opened with fg_flicopen. FG_FLICSIZE returns the dimensions for the flic image associated with the specified flic file header. FG_FLICSKIP advances one or more frames in a flic file previously opened with fg_flicopen. If the last frame played by fg_flicplay displayed the frame from the fg_imagebuf buffer, the frame position will be adjusted in the fg_imagebuf buffer. Otherwise, the flic file position itself will be adjusted. FG_GIFHEAD reads the GIF file's global header and first local header into a 23-byte buffer. FG_GIFMODE determines the optimal video mode for displaying a GIF file. The optimal mode is the video mode having the lowest resolution larger than or equal to the image dimensions. FG_GIFPAL retrieves the palette of an image stored in a GIF file. The palette values are returned as RGB color components, each between 0 and 63. If the GIF file includes a local palette for the first image, fg_gifpal will return the values from the local palette. Otherwise, fg_gifpal will return the values from the GIF file's global palette. FG_GIFRANGE returns the image extents for the GIF image associated with the specified GIF file header. FG_IMAGEBUF specifies the size and address of the buffer used internally when creating or displaying GIF, PCX, FLI/FLC, or SPR/PPR files. Fastgraph's default internal buffer size is 4,096 bytes. Image display or creation is typically faster when a larger buffer is used, especially in protected mode or when playing flic files. In 16-bit environments, the size of the fg_imagebuf buffer is limited to 64K bytes. FG_LOADPCX loads a PCX image into the active virtual buffer. 210 Fastgraph User's Guide FG_MAKEGIF creates a GIF file from the specified rectangular region of the active video page or virtual buffer. The region's extremes are expressed in screen space units. This routine is meaningful only in 16-color and 256- color graphics modes. FG_MAKEPCX creates a PCX file from the specified rectangular region of the active video page or virtual buffer. The region's extremes are expressed in screen space units. FG_MAKEPPR creates a packed pixel run file from the specified rectangular region of the active video page or virtual buffer. The region's extremes are expressed in screen space units. FG_MAKESPR creates a standard pixel run file from the specified rectangular region of the active video page or virtual buffer. The region's extremes are expressed in screen space units. FG_PATTERN defines a display pattern for use when displaying pixel run files in video modes that offer 16 or less colors. FG_PCXHEAD reads a PCX file header into a 128-byte buffer. FG_PCXMODE determines the optimal video mode for displaying a PCX file. The optimal mode is the compatible video mode having the lowest resolution larger than or equal to the image dimensions. FG_PCXPAL retrieves the palette of an image stored in a PCX file. The palette values are returned as RGB color components, each between 0 and 63. If the PCX file includes an extended (256-color) palette, fg_pcxpal will return the values in the extended palette. Otherwise, fg_pcxpal will return the values from the 16-color palette in the PCX header. FG_PCXRANGE returns the image extents for the PCX image associated with the specified PCX file header. FG_SHOWGIF displays an image stored in a GIF file. FG_SHOWFLIC displays an image stored in an FLI or FLC file (collectively called flic files). FG_SHOWPCX displays an image stored in a PCX file. FG_SHOWPPR displays an image stored in a packed pixel run file. The image will be positioned so its lower left corner is at the graphics cursor position of the active video page or virtual buffer. FG_SHOWSPR displays an image stored in a standard pixel run file. The image will be positioned so its lower left corner is at the graphics cursor position of the active video page or virtual buffer.