At the end of this example, we will write 7 lines of FlareScript which generate this image :

We are going to start by simply generating and saving a 1 by 1 pixel image.

<cfx_imageflare source="
  img = Bitmap()
  img.save('C:\example01a.png')
">

img = Bitmap() assigns a new Bitmap object to the variable img.
img.save('C:\example01a.png') saves the image represented by the Bitmap object to C:\example01a.png

These two lines are written in FlareScript, a simple and efficient scripting language.
Using ImageFlare primarily means writing FlareScript directly in the SOURCE attribute, or in a file referenced by the SOURCEFILE attribute.

The tiny image this script creates looks like this »

You will probably want to save images somewhere in a web accessible path. To do this, you can use the expandpath Coldfusion function.

<cfx_imageflare source="
  img = Bitmap()
  img.save('#expandpath('.\example01a.png')#')
">

Now the image is being saved relative to the current directory on the website.
Before an ImageFlare tag is executed, Coldfusion evaluates the text in its attributes.
For example, #expandpath('.\example01a.png')# might become D:\Inetpub\wwwroot\simpleco\example01a.png

These 5 bits of code show different ways to accomplish the very same thing :

<cfx_imageflare source="
  currentdir = '#expandpath('.\')#'
  img = Bitmap()    
  img.save(currentdir..'example01a.png')
">

<cfx_imageflare currentdir="#expandpath('.\')#" source="
  img = Bitmap(1,1)
  img.save(cf.attributes.currentdir..'example01a.png')
">

<cfx_imageflare source=" img=Bitmap(); img.save('#expandpath('.\')#'..'example01a.png'); ">

<cfx_imageflare source=" Bitmap().save('#expandpath('.\')#example01a.png') ">

<cfx_imageflare source=' Bitmap().save("#expandpath(".\")#example01a.png") '>

According to the ImageFlare API, the Bitmap() function is a constructor. This means it creates and returns a Bitmap object.
The API documentation also says this constructor can take either 0 arguments, 2 number arguments, or 1 string argument.

<cfx_imageflare source="
  img = Bitmap( 10, 10 )
  img.fill( Color('red') )
  img.save( '#expandpath('.\')#'..'example01b.png' )
">

Here we are creating a 10x10 pixel image, then filling it with red.

When we pass no arguments to the Bitmap constructor, the Bitmap is initialized to 1 pixel wide and 1 pixel high. When given two numbers, the constructor initializes the image to that width and height, as the ImageFlare API denotes. The fill function is a function Bitmap objects can call, img in this case. Often these `object functions` are referred to as methods of the object. The fill method accepts one argument, a Color object.

The following are a few different ways to create this same image :

<cfx_imageflare source="
  img = Bitmap()
  img.size( 10, 10 )
  img.fill( Color(255,0,0) )
  img.save( '#expandpath('.\')#'..'example01b.png' )
">

<cfx_imageflare source="
  img = Bitmap()
  img.width = 10
  img.height = 10
  img.fill( Color(hex('FF0000')) )
  img.save( '#expandpath('.\')#'..'example01b.png' )
">

<cfx_imageflare source="
  c = Color()
  c.red = 255
  b = Bitmap()
  b.width, b.height = 10, 10
  b.fill( c )
  b.save( '#expandpath('.\')#'..'example01b.png' )
">

Now it's time for something a little more exciting...

This code will create a 100x100 pixel image by placing 100 ten pixel square images of random colors in the main image.
All functions and syntax are properly documented in the ImageFlare API and FlareScript Language sections of the documentation.

<cfx_imageflare debug source="

  b = Bitmap( 100, 100 )
  
  for x=0, 100, 10 do
    for y=0, 100, 10 do
      block = Bitmap( 10, 10 )
      block.fill( Color(random(255),random(255),random(255)) )
      b.paste( block, x, y )
    end
  end
  
  b.save( '#expandpath('.\')#'..'example01c.png' )
">

CFX_IMAGEFLARE Execution Time = 20 ms

First, the debug attribute is available to all CFX, and is not really considered a true attribute. It displays the execution time for a CFX tag.

The for loops provide a way to loop from 0 to 100 by 10 through each column and row in our colorful grid.

for x=0, 100, 10 do

for y=0, 100, 10 do

These loops are nested, which means that for every one iteration of the outermost, the innermost goes through all of its iterations. In this way we are able to loop from left to right in each row, then move onto the next row. The outer loop represents the row, x, and the inner loop represents the column, y.

At the core of the loop we create a new Bitmap, fill it with some random color, then paste it into the main bitmap at the correct location. Creating the temporary bitmap each iteration is hardly necessary. You could create a single temporary Bitmap outside of the loop and only fill/paste it each iteration. Even better, you can create the same resulting image by drawing filled rectangles in the image instead. In fact, both of these things would make the script more efficient.

Our final example incorporates these changes and additionally demonstrates the SOURCEFILE attribute.

<cfx_imageflare debug sourcefile="#expandpath('.\example01d.fs')#" dir="#expandpath('.\')#">

By defining the SOURCEFILE attribute instead of the SOURCE attribute, we have specified the full path to a script file which should be executed.
We have also defined the DIR attribute in order to pass a variable to the SOURCEFILE. We cannot use #expandpath('.\')# inside SOURCEFILE.

The SOURCEFILE, example01d.fs, located at #expandpath('.\example01d.fs')#, contains the following code :

b = Bitmap( 100, 100 )
  
for x=0, 100, 10 do
  for y=0, 100, 10 do
    b.rect( x, y, x+10, y+10, Color(random(255),random(255),random(255)) )
  end
end
  
b.save( cf.attributes.dir..'example01d.png' )

CFX_IMAGEFLARE Execution Time = 10 ms

Since we are no longer creating a new temporary Bitmap object each iteration, execution speed has increased.

Additionally, each square now has a white border. This is because the rect method takes 7 optional arguments, but we have only defined 5 explicitly.
The final two, as defined by the ImageFlare API, are bordercolor and bordersize. Their default values are Color("white") and 1 respectively.

With some slight variations to this script you can generate the following images :

As usual, feel free to contact us with questions.
Click here to return to the examples index, or continue on to Example 2.