USING SOFLARE.DLL
-----------------
The included DLL is an encapsulation of the Lens Flare Toolkit
class. It has been implemented as a DLL to be made available to
other programming languages and to make updating the code easier.

PLEASE READ LICENSE.TXT FOR IMPORTANT INFORMATION REGARDING
USAGE AND DISTRIBUTION.

Please read "FlarLang.html" for information on the Lens Flare
Macro language.

 - Sean O'Malley
   June 24, 2000
   http://www.geocities.com/ffrog.geo

CONTENTS
~~~~~~~~
1) General Usage
2) C++ Usage
3) VB Usage
4) Delphi Usage


GENERAL USAGE:
--------------
The DLL includes one exported function that returns an integer (long).
Currently the integer result is undefined, but generally 0 means
no error and any other number means there was an error. See below
for specific instructions on how to use the DLL with C++, Visual Basic,
and Delphi.

A note on the video buffer: Although it is always referred to as
a buffer containing single bytes in BGR order, it is of course
possible to create a structure/type/record in any of the following
languages that allows you to access the bytes in the video buffer
based on location and color. In C++, for example:

  struct BGRTriplet {
     unsigned char b,g,r;
  };

The vidmem buffer could then be redefined as an array of these
triplets for easier access.

A note on types: The "int" type in definitions below is assumed to 
be a four-byte (signed) integer, AKA "Long" in VB and "Longint" in
Delphi. The "float" type is assumed to be a four-byte floating-point
number, AKA "Single" in VB and Delphi.


C++
---
The RenderData structure is currently defined as:

struct RenderData {
   char *filename;
   int screenx, screeny;
   float lightlocx, lightlocy;
};

The DoFlare function prototype is:

int DoFlare(RenderData *rd, unsigned char *vidmem);

A pointer to a RenderData variable is passed to the DoFlare function 
along with a pointer to a video buffer. The "filename" variable is a 
pointer to the name of an LFM file to process. The "vidmem" variable 
is a pointer to an array of characters describing a BGR-ordered image 
buffer. This buffer should be screenx*screeny*3 bytes long, and can 
either have an image in it already or be empty (flare will be blended 
either way). "screenx" is the width of the image buffer, "screeny" 
is the height of the image buffer. "lightlocx" and "lightlocy" define 
the location of the light source in normalized screen coordinates 
(0-1). Note that this can be overridden by the script file, however.
It is also possible for the light to go off the screen (go below
zero or above one).

To access the DoFlare function, the SOFLARE.DLL must be linked to.
Here is a simple DLL linking example (assumes the <windows.h>
header file has been included). This hasn't been checked for syntax
or typos, though:

 // Type definition for the exported DLL function.
 // (Type defined for ease of casting later on.)
 typedef int (__stdcall *DoF)(RenderData *, unsigned char *);
 // DoFlare: the actual DLL function.
 DoF DoFlare;
 // Windows variables.
 FARPROC tproc;
 HINSTANCE module;

 // Renderdata variable and video memory
 RenderData rd;
 unsigned char *vidmem;

 // Use search path to find soflare.dll
 module = LoadLibrary("soflare");
 // Insert your own error handling here; "module" should not be null!
 assert(module);

 // Get the address of the DoFlare function.
 tproc = GetProcAddress(module, "DoFlare");
 // Insert your own error handling here; "tproc" should not be null!
 assert(tproc); 
 
 // Cast DoFlare function so it works in here.
 DoFlare = (DoF)tproc;

 // USE FLARE FUNCTION HERE
 rd.filename = "c:\flares\test.lfm";
 rd.screenx = [image width]
 rd.screeny = [image height]
 rd.lightlocx = [horizontal light location in normalized screen coords]
 rd.lightlocy = [vertical light location in normalized screen coords]
 vidmem = [pointer to BGR video buffer]
 DoFlare(&rd, vidmem);

 // Clean up
 FreeLibrary(module);


VISUAL BASIC
------------
The VB equivalent of the RenderData struct is:

Type RenderData
  Filename As String
  ScreenX As Long
  ScreenY As Long
  LightLocX As Single
  LightLocY As Single
End Type

A variable of this type is passed to the DoFlare function.
The "Filename" variable is the name of an LFM file to process. 
"ScreenX" is the width of the image buffer, "ScreenY" is the height 
of the image buffer. "LightLocX" and "LightLocY" define the location 
of the light source in normalized screen coordinates (0-1). Note that 
this can be overridden by the script file, however. It is also possible 
for the light to go off the screen (go below zero or above one).

To link to the DoFlare function:

Declare Function DoFlare& Lib "soflare.dll" (ByRef rd As RenderData, ByRef vidmem As Byte)

"vidmem" is a pointer to a video buffer containing ScreenX*ScreenY
BGR triplets (or ScreenX*ScreenY*3 bytes in all). Since VB doesn't
actually handle "pointers", to call the DoFlare function you need to
pass the first byte of the buffer to the function. Since it is defined
"ByRef", Visual Basic will then pass the address of the first byte
(which is what the DLL needs).

A simple example (untested):

 // Define a renderdata variable and a video memory buffer
 Dim rd As RenderData
 Dim vidmem(0 To (3 * 100 * 100) - 1) As Byte
 
 rd.Filename = "c:\Flare\test.lfm"
 rd.ScreenX = 100
 rd.ScreenY = 100
 rd.LightLocX = 0!
 rd.LightLocY = 0! 
 DoFlare rd, vidmem(0)
 
Note how the first byte (in this case 0) of the video buffer is
used when calling the DoFlare function. After this small section
of code is run, the "vidmem" buffer will contain the image produced
by test.lfm. Since VB automatically sets all Dimmed data to zero,
the flare will be drawn on a black background.


DELPHI
------
These instructions and sample code are courtesy of Daniel
Davies @ http://www.daniel-davies.pwp.blueyonder.co.uk/ (His webpage 
also currently contains a complete Delphi project using SOFLARE.DLL.)

The RenderData type is currently defined as:

type RenderData = Record
  FileName  : pChar;
  ScreenX   : LongInt;
  ScreenY   : LongInt;
  LightLocX : Single;
  LightLocY : Single;
end;

The DoFlare function is defined in the interface portion of the
unit as :

function DoFlare(rd : pointer ; vidmem : pointer): integer; stdcall;

then in the implementation portion to link to the DoFlare function :

Function DoFlare; external 'soflare.dll' name 'DoFlare';

A pointer to a RenderData variable is passed to the DoFlare function
along with a pointer to a video buffer. The "FileName" variable is a
pointer to the name of an LFM file to process. [This pointer should
point to a null-terminated C-type string.] The "vidmem" variable
is a pointer to an array of bytes describing a BGR-ordered image 
buffer. This buffer should be screenx*screeny*3 bytes long, and can 
either have an image in it already or be empty (flare will be blended 
either way). "ScreenX" is the width of the image buffer, "ScreenY" is 
the height of the image buffer. "LightLocX" and "LightLocY" define 
the location of the light source in normalized screen coordinates
(0-1). Note that this can be overridden by the script file, however.

A simple untested example :

procedure DrawFlare();
var rd     : RenderData;
    vidmem : array[0..29999] of byte;
begin
  rd.FileName  := 'c:\flare\test.lfm';
  rd.ScreenX   := 100;
  rd.ScreenY   := 100;
  rd.LightLocX := 0;
  rd.LightLocY := 0;
  DoFlare(@rd, @vidmem);
end;

--------------------
- Sean O'Malley
  June 24, 2000
  http://www.geocities.com/ffrog.geo
