
This directory contains the sources for five graphics filters for PCX, MSP,
BMP, GIF and XPM files. The initial code for the first three filters was
written by Maurice Castro and Russell Lang as a part of the dvips driver.
The GIF filter is based on code by Jonathan O' Neal and Steven Bennett. I
adapted the code to Windows and put it in filter form according to the
specifications of Aldus. You can find information on these specifications
on the January-February 1992 issue of Microsoft Systems Journal (which is
also included in the Developers' Network CD) or the July 1992 issue of Dr.
Dobb's journal.

Each filter is a separate DLL and can be used by any program that knows how to
call it. I tested the filters with Dviwin and Word for Windows and they appear
to work fine, except that Word does not use the BMP filter because it imports
BMP files on its own.

The source code is made public to help other people write filters for more
graphics files. If you do this, please send me the code, so I can add it to
the present files and distribute it; in this way, everybody will benefit.


Programming Notes
=================

Each filter exports three functions:

----------------------------------------------------------------------------
WORD FAR PASCAL
GetFilterInfo(WORD version,LPSTR ini_info,LPHANDLE hmem,LPHANDLE filt_types)
----------------------------------------------------------------------------
This routine initializes the filter; the first parameter is a version number
of the program calling the filter; it was initially used by PageMaker, but
it is irrelevant now that other programs can call these filters. The second
parameter (ini_info) is a pointer to a string stored in WIN.INI; this string
may contain options for the filter, but it is ignored in our particular
filters. The third parameter (hmem) is the address of a memory handle. Some
filters present a dialog with several options when you import the file. The
GetFilterInfo function allocates a certain amount of memory to hold the
user's preferences and returns the handle to the caller through this
mechanism. The caller is then expected to call the function GetFilterPref
with the returned handle (that function will put something in that memory
block). Our filters are quite simple, have no options, so they do not use
this parameter. The last parameter is the address of a memory handle which
is reserved for future expansion; right now, the filter does not use this
parameter either. The GetFilterInfo routine returns 2 upon success, or 0 if
the initialization fails. In our case, there is no initialization required,
so the return code is always 2.

----------------------------------------------------------------------------
void FAR PASCAL
GetFilterPref(HANDLE hinst,HWND hwnd,HANDLE hmem,WORD flags)
----------------------------------------------------------------------------
This routine is called after the GetFilterInfo function. Its first parameter
is the instance handle of the caller; the second parameter is the handle to
the parent window. The third parameter is the handle to the memory block
returned by GetFilterInfo (that's where any options are stored). The last
parameter's meaning is specific to the filter. Since our filters do not have
any options, this function does nothing.

-----------------------------------------------------------------------------
WORD FAR PASCAL
ImportGR(HDC hdc,LPFILESPEC fs,LPPICTINFO,HANDLE hmem)
-----------------------------------------------------------------------------
This function actually imports a graphic file and produces a metafile. The
first parameter is the handle to the destination device context; the second
parameter is the address of a FILESPEC structure (defined in filter.h) that
specifies the file to be imported. The third parameter is the address of a
PICTINFO structure (defined in graphio.h) that will receive the metafile
handle and dimensions. The last paramter is the handle to the memory block
containing the options set by GetFilterInfo and GetFilterPref. As explained
above, our filters ignore this parameter. The function should return zero
if the conversion succeeded; if the conversion fails, the function should
return -1, or one of IE_ constants defined in filter.h (the IE_ constants
are preferable to the -1 code since the caller can display an appropriate
error message).


I put some utility functions in the files common1.c and common2.c. These
functions emulate (partially) the standard file and memory allocation
functions. They call the Windows API directly, so the resulting code is
smaller, and more importantly, they do not use any static variables; Windows
DLLs use shared data, so you can get into serious trouble if the DLL uses
static data and two or more processes call DLL functions; this usually
applies to the file and memory functions of the C library.

For more details on the filters, please look at the source code. All files
are meant to be compiled with a large data model (ie., either compact or
large); do NOT use the small or the medium model unless you modify them
extensively.

The filters split the graphic in pieces of 32K bytes; the code is somewhat
clumsy, but this approach circumvents some serious bugs in several video
drivers. The only exception is for RLE compressed BMP files; these are
passed in a single piece.

Hippocrates Sendoukas
isendo@leon.nrcps.ariadne-t.gr
