Controlling the Image Buffer Size

By default, all Fastgraph image file display and creation functions 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() function lets you define your own buffer for this purpose. Larger buffers generally make image display and creation faster. This is especially true when playing flic files, and when reading image files from diskettes or slower CD drives.

The fg_imagebuf() function does not allocate storage for the internal buffer. Rather, it just defines the array or memory block to be used as the buffer. The first parameter passed to fg_imagebuf() is the address of this array or memory block, and the second parameter is the internal buffer size in bytes, represented as an unsigned integer. For example, each of these calls will define a 20,000-byte image buffer:

C/C++:

BYTE Buffer[20000];
fg_imagebuf(Buffer,20000);
BYTE *Buffer;
Buffer = (BYTE *)malloc(20000);
fg_imagebuf(Buffer,20000);
BYTE *Buffer;
Buffer = GlobalAllocPtr(GMEM_MOVEABLE,20000);
fg_imagebuf(Buffer,20000);
BYTE *Buffer;
Buffer = new BYTE[20000];      // C++ only
fg_imagebuf(Buffer,20000);

Delphi:

var
  Buffer : pointer;
begin
  GetMem(Buffer,20000);
  fg_imagebuf(Buffer^,20000);

Visual Basic:

Dim Buffer() As Byte
ReDim Buffer(20000)
Call fg_imagebuf(Buffer, 20000)

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 BMP, PCX, JPEG, 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 once. To do this, specify the FG_FROMBUFFER flag when calling the image display functions. This tells Fastgraph to retrieve the image data from the fg_imagebuf() buffer rather than from the file itself. This method usually provides better performance, especially when playing flic files.

The following code shows how to display a PCX image stored in the fg_imagebuf() buffer. Using standard file I/O functions, it opens the PCX file and reads it into a 48,000-byte buffer. We then pass this buffer to fg_imagebuf(), along with the PCX file size.

C/C++:

BYTE Buffer[48000];
int FileSize;
FILE *Stream;
Stream = fopen("MOUSE.PCX","rb");
FileSize = (int)(filelength(fileno(Stream)));
fread(Buffer,1,FileSize,Stream);
fclose(Stream);
fg_imagebuf(Buffer,FileSize);
fg_showpcx("",FG_FROMBUFFER);

Delphi:

var
  Buffer : pointer;
  Stream : file;
  FileSize : integer;
begin
  AssignFile(Stream,'MOUSE.PCX');
  Reset(Stream,1);
  FileSize := FileSize(Stream);
  GetMem(Buffer,FileSize);
  BlockRead(Stream,Buffer^,FileSize);
  CloseFile(Stream);
  fg_imagebuf(Buffer^,FileSize);
  fg_showpcx('',FG_FROMBUFFER);

Visual Basic:

Dim Buffer() As Byte
Dim FileSize As Long
Open "MOUSE.PCX" For Binary Access Read As #1
FileSize = LOF(1)
ReDim Buffer(FileSize)
Get #1, , Buffer
Close #1
Call fg_imagebuf(Buffer(0), FileSize)
Call fg_showpcx("", FG_FROMBUFFER)

The array used with fg_imagebuf() must of course 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 48,000 bytes). It is crucial that you specify the exact file size when displaying 256-color PCX files so fg_showpcx() can locate the extended (256-color) palette data that might follow the image data. The same is true for flic files, but for BMP and JPEG files we can specify either the file size or the buffer size.

Note that it's not necessary to pass a file name to the image file display functions if the image data resides in the fg_imagebuf() buffer. In other words, the image display functions ignore the file name parameter when FG_FROMBUFFER is specified. However, you must still include a "place holder" parameter where a file name would otherwise be expected. We recommend using the null string as in the above fg_showpcx() example, although any string can be used instead.