ASE Scripting 0.4

                 By David A. Capello, 2005.


#include <std_disclaimer.h>

"I do not accept responsibility for any effects, adverse or otherwise, that this code may have on you, your computer, your sanity, your dog, and anything else that you can think of. Use it at your own risk."


Contents


Introduction

ASE has scripting facilities. You can make a script (a text file) with a set of routines to make images, effects, or anything you think. ASE uses Lua library to do this, so you should know program in Lua, anyway, it's really simple, so you'll not have any inconvenient.

The complete reference of Lua language is in lua-5.0.pdf. Also, you need a text editor to write Lua scripts (the Windows Notepad can be used).


Warning about Lua

You should known that ASE uses a patched version of Lua, where you can use the != operator instead of ~= 

    if current_sprite != nil then
      -- we can use the current_sprite variable...
    end


Basic Lua Programming


Comments

Comments start with -- 

    -- this line will be never parsed
Or you can comment multiple lines 
    --[[
    blah blah blah...
    ]]--

Example 1

    local a = 4
    local b = 5
    print ("a+b is: " .. (a+b))

Here we define two variables "a" and "b" with the values "4" and "5" respectively. Then we print the string "a+b is: " follower by the result of the operation a+b (4+5) that is 9, so the final message is: 

    a+b is: 9
Also we could use: 
    print (a.."+"..b.." is: "..(a+b))
To print: 
    4+5 is: 9

Example 2

    function add (a, b)
      return a+b
    end
    print ("1+2 = " .. add (1, 2))
With the "function" keyword you define a new function, in this case the "add" function, the names between parenthesis indicate the arguments (parameters) that you must give to that routine.


Example 3

    for c = 1, 10 do
      print (c)
    end
This repeat the block between the "do" keyword and the "end" keyword 10 times (from 1 to 10 inclusive).

So this print: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

Example 4

    for c = 1, 10 do
      if c == 5 then
        break
      end
      print (c)
    end
In this case when "c" come to 5 the for is breaked so the other iterations aren't made. This print: 
    1
    2
    3
    4

Example 5

    for c = 1, 5 do
      if c != 3 then
        print ("c isn't 3 (c is " .. c .. ")")
      else
        print ("c is 3")
      end
    end
The != operator means "not equal" (negation of equality). You can use the original Lua operator ~= too.

This print: 

    c isn't 3 (c is 1)
    c isn't 3 (c is 2)
    c is 3
    c isn't 3 (c is 4)
    c isn't 3 (c is 5)

Example 6

    local done = false
    local a = 1
    while not done do
      print (a)
      if a == 3 then
        done = true
      end
      a = a + 1
    end
This print: 
    1
    2
    3
And can be implemented in this way too: 
    local a = 1
    while a <= 3 do
      print (a)
      a = a + 1
    end


ImgType

The imgtype (image-type) is the format of each pixel in a image. Sprites have a lot of images, but all images must have the same imgtype. The know imgtypes are: RGB, Grayscale, Indexed, Bitmap.


IMAGE_RGB

Means that the image have four components (channels or bytes) per pixel, where the values of these components can be between 0 and 255 (256 differents tones), where 255 the maximum intensity.

RGB is RGBA really:

(0,0,0,0) is mask color, (0,0,0,255) is black, and (255,255,255,255) is white.


IMAGE_GRAYSCALE

The image has two channels (two bytes) per pixel.

(0,0) is mask color, (0,255) is black, (255,255) is white.


IMAGE_INDEXED

Image uses one byte per pixel:

In this imgtype, each pixel hasn't the color information, only has a reference to the color-palette (from 0 to 255, 256 colors), so the RGB information about the color is found in the color-palette and not in the image.

The index=0 is the mask color.


IMAGE_BITMAP

An internal imgtype to handle masks, where a pixel is a bit, and 8 pixels are a byte. 1 means selected, 0 deselected.


Standard routines


double MAX (double x, double y);

Returns the maximum value.


double MIN (double x, double y);

Returns the minimum value.


double MID (double x, double y, double z);

Limits the y value to x and z.


void include (const char *filename);

void dofile (const char *filename);

Process the script that is in the file with the given filename. It's searched in the current and in the "data/scripts" directories.


void print (const char *buf);

Prints a message in the console, this is useful mainly to debug scripts or to show errors.


double rand (double min, double max);

Returns a random number between min and max values.


String routines


const char *_ (const char *msgid);

Tries to translate the string msgid to the current language, the entry must exists in the .po file.


int strcmp (const char *s1, const char *s2);

Compares the two strings s1 and s2. It returns an integer less than, equal to, or greater than zero if s1 is found, respectively, to be less than, to match, or be greater than s2.


Math routines


Constants

PI: the ratio of a circle's circumference to its diameter (3.141592...).


Routines


double fabs (double x);

Return the absolute value of the number x.


double ceil (double x);

This funtion rounds x up to the nearest integer.
See also: floor.
double floor (double x);

This funtion rounds x down to the nearest integer.
See also: ceil.
double exp (double x);

Returns the value of e (the base of natural logarithms) raised to the power of x.
See also: log.
double log (double x);

Returns the natural logarithm of x.
See also: exp, log10.
double log10 (double x);

Returns the base-10 logarithm of x.
See also: log.
double pow (double x, double y);

Returns the value of x raised to the power of y.
See also: sqrt.
double sqrt (double x);

Returns the non-negative square root of x.
See also: hypot, pow.
double hypot (double x, double y);

Returns the sqrt(x*x + y*y). This is the length of the hypotenuse of a right-angle triangle with sides of length x and y, or the distance of the point (x, y) from the origin.
See also: sqrt.
double cos (double x);

Returns the cosine of x, where x is given in radians.
See also: sin, tan, acos.
double sin (double x);

Returns the sine of x, where x is given in radians.
See also: cos, tan, asin.
double tan (double x);

Returns the tangent of x, where x is given in radians.
See also: cos, sin, atan.
double acos (double x);

Returns the arc cosine in radians and the value is mathematically defined to be between 0 and PI (inclusive).
See also: cos.
double asin (double x);

Returns the arc sine in radians and the value is mathematically defined to be between -PI/2 and PI/2 (inclusive).
See also: sin.
double atan (double x);

Returns the arc tangent in radians and the value is mathematically defined to be between -PI/2 and PI/2 (inclusive).
See also: tan, atan2.
double atan2 (double y, double x);

Returns the result in radians, which is between -PI and PI (inclusive).
See also: atan.
double cosh (double x);

Returns the hyperbolic cosine of x, which is defined mathematically as (exp(x) + exp(-x)) / 2.


double sinh (double x);

Returns the hyperbolic sine of x, which is defined mathematically as (exp(x) - exp(-x)) / 2.


double tanh (double x);

Returns the hyperbolic tangent of x, which is defined mathematically as sinh(x) / cosh(x).


File routines


bool file_exists (const char *filename);

Checks whether a file matching the given name exists, returning true if it does.


char *get_filename (const char *filename);

When passed a completely specified file path, this returns a pointer to the filename portion. Both ´\´ and ´/´ are recognized as directory separators.


Objects

There are a special type of variables in Lua scripts: objects (represented with user-data). Each object can be of some of these types:


Image

An image, has width and height, an image-type (RGB, Grayscale, etc.), and contains the image data (pixels, pixmap, or bitmap).


Image fields


Image methods


Image *image_new (int imgtype, int w, int h);

Creates a new image


Image *image_new_copy (Image *image);


void image_free (Image *image);


int image_getpixel (Image *image, int x, int y);


void image_putpixel (Image *image, int x, int y, int color);


void image_clear (Image *image, int color);


void image_copy (Image *dst, Image *src, int x, int y);


void image_merge (Image *dst, Image *src, int x, int y, int opacity, int blend_mode);


Image *image_crop (Image *image, int x, int y, int w, int h);


void image_hline (Image *image, int x1, int y, int x2, int color);


void image_vline (Image *image, int x, int y1, int y2, int color);


void image_rect (Image *image, int x1, int y1, int x2, int y2, int color);


void image_rectfill (Image *image, int x1, int y1, int x2, int y2, int color);


void image_line (Image *image, int x1, int y1, int x2, int y2, int color);


void image_ellipse (Image *image, int x1, int y1, int x2, int y2, int color);


void image_ellipsefill (Image *image, int x1, int y1, int x2, int y2, int color);


void image_convert (Image *dst, Image *src);


int image_count_diff (Image *i1, Image *i2);


Frame

A frame of animation, it contains the position, opacity and a reference (by index) to some image in the image's stock of the layer where this frame is. Remember this, a frame doesn't contain the image, only a reference to it.


Frame *frame_new (int frpos, int image, int x, int y, int opacity);


Frame *frame_new_copy (Frame *frame);


void frame_free (Frame *frame);


Frame *frame_is_link (Frame *frame, Layer *layer);


void frame_set_frpos (Frame *frame, int frpos);


void frame_set_image (Frame *frame, int image);


void frame_set_position (Frame *frame, int x, int y);


void frame_set_opacity (Frame *frame, int opacity);


Layer

A layer can be two things: a normal layer (also called image layer), or a layer set. A layer set is a group of child layers (like "sprite.set"). A normal layer is a complete different thing.

A normal layer has a stock of images and a list of frames, each frame has a reference to the image's stock, so each frame uses some image of the stock. If two frames uses the same stock images, the first frame is called the "original frame" and all other frames are called "links".


Layer *layer_new (int imgtype);


Layer *layer_set_new (void);


Layer *layer_new_copy (Layer *layer);


Layer *layer_new_with_image (int imgtype, int x, int y, int w, int h, int frpos);


void layer_free (Layer *layer);


bool layer_is_image (Layer *layer);


bool layer_is_set (Layer *layer);


Layer *layer_get_prev (Layer *layer);


Layer *layer_get_next (Layer *layer);


void layer_set_name (Layer *layer, const char *name);


void layer_set_blend_mode (Layer *layer, int blend_mode);


void layer_add_frame (Layer *layer, Frame *frame);


void layer_remove_frame (Layer *layer, Frame *frame);


Frame *layer_get_frame (Layer *layer, int frpos);


void layer_add_layer (Layer *set, Layer *layer);


void layer_remove_layer (Layer *set, Layer *layer);


void layer_move_layer (Layer *set, Layer *layer, Layer *after);


void layer_render (Layer *layer, Image *image, int x, int y, int frpos);


Layer *layer_flatten (Layer *layer, int imgtype, int x, int y, int w, int h, int frmin, int frmax);


Mask


Mask *mask_new (void);


Mask *mask_new_copy (Mask *mask);


void mask_free (Mask *mask);


bool mask_is_empty (Mask *mask);


void mask_set_name (Mask *mask, const char *name);


void mask_move (Mask *mask, int x, int y);


void mask_none (Mask *mask);


void mask_invert (Mask *mask);


void mask_replace (Mask *mask, int x, int y, int w, int h);


void mask_union (Mask *mask, int x, int y, int w, int h);


void mask_subtract (Mask *mask, int x, int y, int w, int h);


void mask_intersect (Mask *mask, int x, int y, int w, int h);


void mask_merge (Mask *dst, Mask *src);


void mask_by_color (Mask *mask, Image *image, int color, int fuzziness);


void mask_crop (Mask *mask, Image *image);


Path


Path *path_new (const char *name);


void path_free (Path *path);


void path_set_join (Path *path, int join);


void path_set_cap (Path *path, int cap);


void path_moveto (Path *path, double x, double y);


void path_lineto (Path *path, double x, double y);


void path_curveto (Path *path, double control_x1, double control_y1, double control_x2, double control_y2, double end_x, double end_y);


void path_close (Path *path);


void path_move (Path *path, double x, double y);


void path_stroke (Path *path, Image *image, int color, double brush_size);


void path_fill (Path *path, Image *image, int color);


Sprite

The sprite is the main object of ASE (remember Allegro "Sprite" Editor), and it's the structure that contains all data: layers, frames, stocks, images, masks, paths, and undo information are inside the same sprite.

There are a global variable of Sprite type: current_sprite. This could be "nil" if there aren't a selected sprite in the moment.

You should known about the difference between the "current_sprite" in scripts and the sprite in the current editor. Because when you select a sprite with "set_current_sprite", only the "current_sprite" global pointer is set, but the sprite in the current editor is maintain intact. So when ASE runs a script, the "current_sprite" will be pointing to the sprite in the current editor, but if you change the "current_sprite" (with "set_current_sprite" routine) you'll not get that sprite in the editor (use "sprite_show" function instead).


Sprite *sprite_new (int imgtype, int w, int h);


Sprite *sprite_new_copy (Sprite *sprite);


Sprite *sprite_new_flatten_copy (Sprite *sprite);


Sprite *sprite_new_with_layer (int imgtype, int w, int h);


void sprite_free (Sprite *sprite);


void sprite_lock (Sprite *sprite);


void sprite_unlock (Sprite *sprite);


bool sprite_is_locked (Sprite *sprite);


bool sprite_is_modified (Sprite *sprite);


void sprite_was_saved (Sprite *sprite);


void sprite_set_filename (Sprite *sprite, const char *filename);


void sprite_set_size (Sprite *sprite, int w, int h);


void sprite_set_frames (Sprite *sprite, int frames);


void sprite_set_speed (Sprite *sprite, int speed);


void sprite_set_path (Sprite *sprite, Path *path);


void sprite_set_mask (Sprite *sprite, Mask *mask);


void sprite_set_layer (Sprite *sprite, Layer *layer);


void sprite_set_frpos (Sprite *sprite, int frpos);


void sprite_set_imgtype (Sprite *sprite, int imgtype, int dithering_method);


void sprite_add_path (Sprite *sprite, Path *path);


void sprite_remove_path (Sprite *sprite, Path *path);


void sprite_add_mask (Sprite *sprite, Mask *mask);


void sprite_remove_mask (Sprite *sprite, Mask *mask);


Mask *sprite_request_mask (Sprite *sprite, const char *name);


void sprite_render (Sprite *sprite, Image *image, int x, int y);


Stock

Stock of images. Each image layer has its own image's stock to provide images to its frames.


Stock *stock_new (int imgtype);


Stock *stock_new_copy (Stock *stock);


void stock_free (Stock *stock);


int stock_add_image (Stock *stock, Image *image);


void stock_remove_image (Stock *stock, Image *image);


void stock_replace_image (Stock *stock, int index, Image *image);


Image *stock_get_image (Stock *stock, int index);


Undo


Undo *undo_new (Sprite *sprite);


void undo_free (Undo *undo);


void undo_enable (Undo *undo);


void undo_disable (Undo *undo);


bool undo_is_enabled (Undo *undo);


bool undo_is_disabled (Undo *undo);


bool undo_can_undo (Undo *undo);


bool undo_can_redo (Undo *undo);


void undo_undo (Undo *undo);


void undo_redo (Undo *undo);


void undo_open (Undo *undo);


void undo_close (Undo *undo);


void undo_image (Undo *undo, Image *image, int x, int y, int w, int h);


void undo_flip (Undo *undo, Image *image, int x1, int y1, int x2, int y2, int horz);


void undo_add_image (Undo *undo, Stock *stock, Image *image);


void undo_remove_image (Undo *undo, Stock *stock, Image *image);


void undo_replace_image (Undo *undo, Stock *stock, int index);


void undo_add_frame (Undo *undo, Layer *layer, Frame *frame);


void undo_remove_frame (Undo *undo, Layer *layer, Frame *frame);


void undo_add_layer (Undo *undo, Layer *set, Layer *layer);


void undo_remove_layer (Undo *undo, Layer *layer);


void undo_move_layer (Undo *undo, Layer *layer);


void undo_set_layer (Undo *undo, Sprite *sprite);


void undo_set_mask (Undo *undo, Sprite *sprite);


Effect


Effect *effect_new (Sprite *sprite, const char *name);


void effect_free (Effect *effect);


void effect_load_target (Effect *effect);


void effect_set_target (Effect *effect, bool r, bool g, bool b, bool k, bool a, bool index);


void effect_set_target_rgb (Effect *effect, bool r, bool g, bool b, bool a);


void effect_set_target_grayscale (Effect *effect, bool k, bool a);


void effect_set_target_indexed (Effect *effect, bool r, bool g, bool b, bool index);


void effect_begin (Effect *effect);


void effect_begin_for_preview (Effect *effect);


int effect_apply_step (Effect *effect);


void effect_apply (Effect *effect);


void effect_flush (Effect *effect);


void effect_apply_to_image (Effect *effect, Image *image, int x, int y);


void effect_apply_to_target (Effect *effect);


ConvMatr


ConvMatr *convmatr_new (int w, int h);


ConvMatr *convmatr_new_string (const char *format);


void convmatr_free (ConvMatr *convmatr);


Convolution Matrix Effect


void set_convmatr (ConvMatr *convmatr);


ConvMatr *get_convmatr (void);


ConvMatr *get_convmatr_by_name (const char *name);


Curve

Curve is a type to represent a function y=f(x). It's mainly used in color-curve effect.


Curve *curve_new (int type);

Creates a new curve, type can be CURVE_LINEAR or CURVE_SPLINE.


void curve_free (Curve *curve);


void curve_add_point (Curve *curve, CurvePoint *point);


void curve_remove_point (Curve *curve, CurvePoint *point);


Color Curve Effect


void set_color_curve (Curve *curve);


CurvePoint


CurvePoint *curve_point_new (int x, int y);


void curve_point_free (CurvePoint *point);


JEvent


JList


JRect


JRect fields


JRegion


JWidget


Index

  • MAX
  • MID
  • MIN
  • _
  • acos
  • asin
  • atan
  • atan2
  • ceil
  • convmatr_free
  • convmatr_new
  • convmatr_new_string
  • cos
  • cosh
  • curve_add_point
  • curve_free
  • curve_new
  • curve_point_free
  • curve_point_new
  • curve_remove_point
  • dofile
  • effect_apply
  • effect_apply_step
  • effect_apply_to_image
  • effect_apply_to_target
  • effect_begin
  • effect_begin_for_preview
  • effect_flush
  • effect_free
  • effect_load_target
  • effect_new
  • effect_set_target
  • effect_set_target_grayscale
  • effect_set_target_indexed
  • effect_set_target_rgb
  • exp
  • fabs
  • file_exists
  • floor
  • frame_free
  • frame_is_link
  • frame_new
  • frame_new_copy
  • frame_set_frpos
  • frame_set_image
  • frame_set_opacity
  • frame_set_position
  • get_convmatr
  • get_convmatr_by_name
  • get_filename
  • hypot
  • image_clear
  • image_convert
  • image_copy
  • image_count_diff
  • image_crop
  • image_ellipse
  • image_ellipsefill
  • image_free
  • image_getpixel
  • image_hline
  • image_line
  • image_merge
  • image_new
  • image_new_copy
  • image_putpixel
  • image_rect
  • image_rectfill
  • image_vline
  • include
  • layer_add_frame
  • layer_add_layer
  • layer_flatten
  • layer_free
  • layer_get_frame
  • layer_get_next
  • layer_get_prev
  • layer_is_image
  • layer_is_set
  • layer_move_layer
  • layer_new
  • layer_new_copy
  • layer_new_with_image
  • layer_remove_frame
  • layer_remove_layer
  • layer_render
  • layer_set_blend_mode
  • layer_set_name
  • layer_set_new
  • log
  • log10
  • mask_by_color
  • mask_crop
  • mask_free
  • mask_intersect
  • mask_invert
  • mask_is_empty
  • mask_merge
  • mask_move
  • mask_new
  • mask_new_copy
  • mask_none
  • mask_replace
  • mask_set_name
  • mask_subtract
  • mask_union
  • path_close
  • path_curveto
  • path_fill
  • path_free
  • path_lineto
  • path_move
  • path_moveto
  • path_new
  • path_set_cap
  • path_set_join
  • path_stroke
  • pow
  • print
  • rand
  • set_color_curve
  • set_convmatr
  • sin
  • sinh
  • sprite_add_mask
  • sprite_add_path
  • sprite_free
  • sprite_is_locked
  • sprite_is_modified
  • sprite_lock
  • sprite_new
  • sprite_new_copy
  • sprite_new_flatten_copy
  • sprite_new_with_layer
  • sprite_remove_mask
  • sprite_remove_path
  • sprite_render
  • sprite_request_mask
  • sprite_set_filename
  • sprite_set_frames
  • sprite_set_frpos
  • sprite_set_imgtype
  • sprite_set_layer
  • sprite_set_mask
  • sprite_set_path
  • sprite_set_size
  • sprite_set_speed
  • sprite_unlock
  • sprite_was_saved
  • sqrt
  • stock_add_image
  • stock_free
  • stock_get_image
  • stock_new
  • stock_new_copy
  • stock_remove_image
  • stock_replace_image
  • strcmp
  • tan
  • tanh
  • undo_add_frame
  • undo_add_image
  • undo_add_layer
  • undo_can_redo
  • undo_can_undo
  • undo_close
  • undo_disable
  • undo_enable
  • undo_flip
  • undo_free
  • undo_image
  • undo_is_disabled
  • undo_is_enabled
  • undo_move_layer
  • undo_new
  • undo_open
  • undo_redo
  • undo_remove_frame
  • undo_remove_image
  • undo_remove_layer
  • undo_replace_image
  • undo_set_layer
  • undo_set_mask
  • undo_undo