Lens Flare Macro Language
A complete lens flare is composed of one or more "spots" or Flares arranged along the Flare Axis. The Lens Flare Macro (LFM) language allows the description of a complete flare by positioning, coloring and shaping these individual flare elements.

These flare elements (Flare Types) can be anything from a simple spot to a polygon to a complex star or other image. The language allows the creation ("registering") of new Flare Types using Windows BMP files. All Flare Types must be registered before first being used, with the exception of Pre-Registered Flare Types which are automatically generated and can be referred to without explicit registering (see the RegisterFlare command below).

For reasons of flexibility, the language was made so that the complete Lens Flare will appear as identically as possible on all images and screens no matter the resolution. Because of this, you may notice that there is no absolute coordinate system, but most commands requiring coordinates accept them in terms of normalized screen or axis coordinates using decimal numbers.

Important: Keep in mind that the Lens Flare Macro language is extremely case-sensitive. DRAWFLARE is not the same as DrawFlare! Also make sure that Flares are referred to by the exact name they were registered with.

Comments
Comments are ignored sections of code. There are two types of comment: single-line and multi-line:

 ; This is a comment.
 { This is a comment.
   This, too. }

Multi-line comments encapsulate all text enclosed in the { }. Single-line comments need only have a ; character before the line. It is illegal to have either kind of comment on a line with any other command, however:

 DrawFlare SimpleSpot  ; This is illegal!

 { This is
   illegal! } RegisterFlare MyStar
 c:\Flares\star.bmp    { This is illegal! }

Registering Flares
Before any non-pre-registered Flares can be drawn, they need to be registered. The command for registering a flare is:

• RegisterFlare [Flare Name]
  [BMP Image (Path+Filename)]

The Flare Name is a single word (ex. LittleStar) used to refer to the Flare later on in DrawFlare commands (see below). The BMP Image should be the complete path and filename of a BMP image to use for this flare (ex. C:\FLARES\LITTLESTAR.BMP). Spaces are allowed for long filenames, but keep in mind this filename and path must be the only thing on the line immediately following the RegisterFlare command. The BMP should be a standard 24-bit (TrueColor) square bitmap. Colors are ignored since color is controlled using the Color command (see below). Though the BMP must be square, the flare inside need not be, or use the Aspect command to change the shape of the Flare.

The pre-registered Flares are:

• SimpleSpot A simple round spot that occurs in 99% of flares.
• ReverseSpot Another very common round spot that dims toward the center.
• PentagonSpot A perfect pentagon; can distort with the Aspect command.
• ThinHalo A thin halo useful for a lot of things.

Drawing Flares
The command to draw a Flare is:

• DrawFlare [Flare Name]

Where Flare Name is the name the Flare was registered under or the name of the pre-registered Flare. Remember that commands affecting the appearance of the Flare should be executed before the Flare is drawn!

Commands
All Flare commands can be used in any order in a Lens Flare Macro file and are executed in order. Flare commands modify the appearance of all Flares coming after them and are not changed when Flares are drawn. Though most Flare parameters have defaults, it is still important for most Flare commands to be executed before using the DrawFlare command. For instance, while the Aspect Ratio has a default of 1.0 and may not be necessary to change before drawing the first flare, it is almost certainly necessary to change the Color before drawing the first flare. (In fact, the default color may be [0,0,0] and no Flare will appear!) The same goes for commands like Location, Size and others critical to the appearance of the Flare.

• Location [Coordinate_System] [Coordinate(s)]
  Sets the location of the Flare. Coordinate_System should either be the word Absolute or the word Axis. Absolute means the Flare is located in relation to the sides of the image. Axis means the Flare is positioned along the Flare Axis.
  
  Depending on the Coordinate_System, the Coordinate(s) should be:
  • If Absolute: Coordinates should be a pair of decimal numbers defining the location of the Flare in relation to the sides of the image. Coordinates 0.0 0.0 would be the top-left of the image, 1.0 1.0 would be the lower-right, 0.5 0.5 would be the center of the image, etc.
    
    
  • If Axis: Coordinate should be a single decimal number defining the location of the Flare along the Flare Axis. 0.0 would be directly on the light source, 1.0 would be diametrically opposed to the light source (in relation to the center of the image), 0.5 would be the center of the image. Note that numbers greater than 1.0 and less than 0.0 can be used, and in fact are needed frequently for realistic flares.
  
  
  Example: Location Axis 0.0
  Positions subsequent Flares directly on the light source.
  
  
• Color [R G B]
  Sets the color of the Flare. Should be three decimal numbers from 0.0-1.0. 1.0 0.0 0.0 would be pure red, 1.0 1.0 1.0 would be pure white, etc. The color is also modified by the SetBrightness command.
  
  Example: Color 1.0 1.0 0.3
  Changes the color of subsequent Flares to a bright yellow.
  
  
• SetBrightness [+/-][Brightness]
  Adjusts the brightness. The Color of each Flare is multiplied by the Brightness value when it is being drawn. The Brightness value defaults to 1.0, which means no change is made to the Color of the Flare. If this command is executed without a + or - sign, the Brightness is set to that value absolutely. If a + or - is included, it increases or decreases the Brightness by that amount. For most Flares it may be a good idea to set the absolute Brightness only once at the beginning of the Flare file and add or subtract to it as necessary. That way, if the entire Flare is too dim or too bright for a particular image, changing the absolute Brightness at the beginning of the macro file will change the Brightness of the overall Lens Flare without changing the Brightness of each Flare element in relation to each other.
  
  Examples:
  SetBrightness 0.5
  The Color values of all subsequently drawn Flares will be halved.
  
  SetBrightness +0.1
  Increases the brightness of subsequent Flares by 10%.
  
  
• Size [Size]
  Horizontal size of the Flare in percentage of the width of the screen or image on which it is being overlayed. In other words, 100 would mean the horizontal width of the Flare is equal to the width of the window into which it is being drawn; 50 would mean the width of the Flare is half the width of the window, etc. (Note that some Flares may not appear to be the size of other Flares even when their Sizes are the same; this is because some flares take up more area in their original matrix than others.)
  
  Example: Size 25
  The width of subsequent Flares will be ¼ the width of the screen or image on which the Flare is being overlayed.
  
  
• Aspect [Aspect]
  A decimal number defining the aspect ratio of the Flare (width÷height). This can be used to widen or lengthen the flare (especially useful with stars!). Numbers greater than 1.0 stretch the flare horizontally, and numbers larger than 0.0 but less than 1.0 stretch it vertically. (4.0 would mean the Flare is four times wider than it is tall; 0.25 would mean the Flare is four times taller than it is wide.) NOTE: Aspect only modifies the vertical size of the flare; horizontal size is controlled by the Size command.
  
  Example: Aspect 1.5
  Changes the aspect ratio of subsequent Flares so they are ½ wider than they are tall.
  
  
• SetRotation [Coordinate_System] [±Degrees]
  Changes the rotation angle of subsequent Flares.
  
  If Coordinate_System is Axis, Flares are rotated to be kept in line with the Flare Axis and Degrees sets the amount of deviation from this line. For instance, if the light is located at [0,0], the Flare Axis will be oriented at -45 degrees. If the deviation is 0.0, all subsequent Flares will be rotated -45 degrees from "north"; if the deviation is -10, subsequent Flares will be rotated -55 degrees, etc.
  
  If Coordinate_System is Absolute, Flares will be rotated Degrees degrees from "north". The default setting (no rotation and no axis alignment) is equivalent to SetRotation Absolute 0.0.
  
  Note: The Flare matrix is rotated after any aspect ratio changes to avoid distortion.
  
  
• SetLightLocation [x y]
  Sets the location of the light source, changing the position and orientation of the Flare Axis for all subsequent axis-oriented Flares drawn. The X,Y coordinates are in normalized screen coordinates; 0.0 0.0 is the top-left, 1.0 1.0 is the bottom-right. Since Flares are sometimes visible even when the light source is off the screen, these numbers can also be less than 0.0 or greater than 1.0.
  
  Note that depending on the implementation of the Flare code, the light location may be set automatically making manual adjustment unnecessary.
  
  Example: SetLightLocation 1.0 0.0
  Moves the light to the top-right corner of the screen or image and re-orients the Flare Axis accordingly.