Writing Templates for Sprite

Sprite writes the beginning of a formula and simply finishes it off with whatever is in the template file. This guide presumes that you are already proficient at writing Ultra Fractal formulas. 

A template file begins with a series of command comment lines that tell Sprite how to behave:

;ucl This tells Sprite that it is writing a coloring algorithm. This really only determines what extension is used by default in the "Select a formula file" dialog box, so templates should follow the format required by the formula type.
;ufm This tells Sprite that it is writing a fractal formula.
;uxf This tells Sprite that it is writing a transformation. If more than one of these three commands appear then it is the final one that is used.
;noalpha This tells Sprite to ignore the alpha channel of the image and give each pixel full opacity. This can create more efficient formulas if a PNG image with an alpha channel is loaded but the template makes no use of it.
;greyscale This tells Sprite to convert the image to greyscale before creating the formula. If the template makes no use of the color information this can create smaller and more efficient formulas.
;begin This tells Sprite to stop looking for command comments. This must be the final command and it is required in all templates.

Command comments must use the exact format shown: a semi-colon followed immediately by the command, with nothing else on the line. Other comments can be added on separate lines and they will be ignored.

Sprite writes the image data into an array simply called c, and defines two variables called image_width and image_ height. Valid indices for the array range from c[0, 0] to c[image_width - 1, image_height - 1]

Immediately below the ;begin command the template starts in the Global section of the formula.

The red, green, blue and alpha values for each pixel are packed into a single integer array, and so the integer has to be decoded by the formula. The following code snippet demonstrates how to extract the individual values at location (x, y) in the image:

int rgba = c[x, y]
if (rgba < 0)
  rgba = (rgba + 2147483647) + 1
  int alpha = 128 + trunc(rgba / 16777216)
  alpha = trunc(rgba / 16777216)
int red = rgba % 256
int green = trunc(rgba / 256) % 256
int blue = trunc(rgba / 65536) % 256

The color components and alpha values range from 0 to 255 so they need to be divided by 255 before they can be converted to a color variable or used in Ultra Fractal's color functions:

color acolor = rgba(red / 255, green / 255, blue / 255, alpha / 255)

The best way to create a new template is to create a formula using an existing template and edit the formula in Ultra Fractal as you would any new formula. When it's working to your satisfaction copy everything below the image array and paste it into a new text file. You can then create a formula from your new template, work on it some more, and repeat the process as needed.

A hint: rather then scroll through all of the image data to get to the interesting part of the formula, use the shortcut Shift+Ctrl+Down.

Finally you can edit the title of the formula to show the name that you want displayed next to the "Select a template..." button when the template is loaded into Sprite. You do this last because each time you create a formula from the template it will be overwritten by the formula name. Apart from any leading spaces, the format of the title line must be exact: title, space, equals sign, space, opening quotation marks.

You can use the supplied templates as the starting point for your explorations, but bear in mind that these don't necessarily demonstrate the best way to do things. Only the format of the image array is fixed, templates can do anything that you want them to. If you have any suggestions for the improvement of the supplied templates, or to share what you've created, join the Sprite Users Group.