Retrieving Images

Another important Fastgraph/Image feature is the ability to retrieve files from an FGI library. This makes it possible to store any type of file, not just images, in a library and then manipulate or display the files as needed. For example, you can retrieve a PCX image into the fg_imagebuf() buffer and then use Fastgraph's fg_showpcx() function to display the image from the buffer. Or, you can retrieve a bitmapped image and use the bitmap display functions such as fg_drwimage() to display it. Yet another possibility might be to store strings for different languages in separate files within an FGI library and then retrieve the strings file for the desired language.

This section will show how to use the Fastgraph/Image fgi_read() function to retrieve image files from libraries. While retrieving image files and displaying them in a separate operation may sometimes be useful, it's much easier to use fgi_display() or one of the image-specific display functions to accomplish this in one step. Nevertheless, image files provide a simple starting point to discuss fgi_read().

The first parameter passed to fgi_read() is the name of the file to retrieve, terminated by a null character, while the second parameter is an array that will receive the contents of that file. The third parameter is the file handle for the FGI library containing the requested file. The possible fgi_read() return values are the same as those of fgi_display().

The array that receives the file contents can be either a fixed-size array or a pointer to a dynamically allocated memory block. If your program allocates memory for the array, you can use fgi_filesize() to determine the size of the block to allocate. This function expects its first parameter to be a null-terminated file name and its second parameter to be the file handle for the FGI library containing that file. Its return value is the file size in bytes. Possible error conditions are an error reading the FGI library (-1) or the requested file is not in the FGI library (-2).