PCX Helper Functions

There are four additional functions that work with PCX files. The fg_pcxpal() function retrieves the palette of a PCX image. Its first parameter is a PCX file name, terminated by a zero byte as with fg_showpcx(). Its second parameter is the name of the array that will receive the PCX palette values. The palette values are returned as RGB color components, each between 0 and 255. 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() return value is the number of colors in the PCX palette (either 16 or 256), or 0 if the PCX file does not contain a palette (this will be the case for 24-bit PCX files). The possible error return values are -1 (file not found) and -2 (file is not a PCX file). You can also specify NULL for the second fg_pcxpal() parameter (pass nil^ for Delphi, ByVal 0 for Visual Basic, or BYVAL %NULL for PowerBASIC). In this case, the function will return the image's color depth but no palette values.

The fg_pcxhead() function retrieves a PCX file header. The first fg_pcxhead() parameter is the name of a PCX file (terminated by a zero byte), and the second is the name of a buffer that will receive the PCX header (the buffer size must be at least 128 bytes). If successful, fg_pcxhead() returns zero. Otherwise, the return value is -1 if the specified file was not found, or -2 if it is not a PCX file.

The fg_pcxsize() function returns the width and height of a PCX image. Its first parameter is the name of a buffer containing the PCX file header returned by fg_pcxhead(), and its second and third parameters receive the image width and height in pixels. If the PCX file header is not valid, fg_pcxsize() returns -1 for the width and height parameters.

The fg_pcxrange() function is similar, but it returns the image position information from the PCX header. The first fg_pcxrange() parameter is the name of a buffer containing a PCX file header. The remaining four parameters receive the minimum x, maximum x, minimum y, and maximum y values of the corresponding PCX image. If the PCX file header is not valid, fg_pcxrange() returns -1 for the four position parameters. 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.