 This is the Info version of the ASE Scripting manual

 By David
A. Capello

                         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."

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:

        * R: Red.

        * G: Green.

        * B: Blue.

        * A: Alpha (transparency or opacity).

 (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.

        * K: Luminance (or black channel)

        * A: Alpha (transparency or opacity).

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

IMAGE_INDEXED
=============

 Image uses one byte per pixel:

        * Index: index of the color that we must use from the
          color-palette.

 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
*****************

MAX
===

double MAX (double x, double y);
     Returns the maximum value.

MIN
===

double MIN (double x, double y);
     Returns the minimum value.

MID
===

double MID (double x, double y, double z);
     Limits the y value to x and z.

include
=======

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.

print
=====

void print (const char *buf);
     Prints a message in the console, this is useful mainly to debug
     scripts or to show errors.

rand
====

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.

strcmp
======

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
========

fabs
====

double fabs (double x);
     Return the absolute value of the number x.

ceil
====

double ceil (double x);
     This funtion rounds x up to the nearest integer.

 See also:

 floor.

floor
=====

double floor (double x);
     This funtion rounds x down to the nearest integer.

 See also:

 ceil.

exp
===

double exp (double x);
     Returns the value of e (the base of natural logarithms) raised to
     the power of x.

 See also:

 log.

log
===

double log (double x);
     Returns the natural logarithm of x.

 See also:

 exp.

 See log10.

log10
=====

double log10 (double x);
     Returns the base-10 logarithm of x.

 See also:

 log.

pow
===

double pow (double x, double y);
     Returns the value of x raised to the power of y.

 See also:

 sqrt.

sqrt
====

double sqrt (double x);
     Returns the non-negative square root of x.

 See also:

 hypot.

 See pow.

hypot
=====

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.

cos
===

double cos (double x);
     Returns the cosine of x, where x is given in radians.

 See
also:

 sin.

 See tan.

 See acos.

sin
===

double sin (double x);
     Returns the sine of x, where x is given in radians.

 See also:

 cos.

 See tan.

 See asin.

tan
===

double tan (double x);
     Returns the tangent of x, where x is given in radians.

 See
also:

 cos.

 See sin.

 See atan.

acos
====

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.

asin
====

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.

atan
====

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.

 See atan2.

atan2
=====

double atan2 (double y, double x);
     Returns the result in radians, which is between -PI and PI
     (inclusive).

 See also:

 atan.

cosh
====

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

sinh
====

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

tanh
====

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

File routines
*************

file_exists
===========

bool file_exists (const char *filename);
     Checks whether a file matching the given name exists, returning
     true
 if it does.

get_filename
============

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:

   * Graphics objects: Image, Frame, Layer, Mask, Path, Sprite, Stock,
     Undo.

   * Effect objects: Effect, ConvMatr, Curve, CurvePoint.

   * GUI objects: JEvent, JList, JRect, JRegion, JWidget.

Image
*****

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

Image fields
============

        * [number] image.imgtype

 See sprite.imgtype

        * [number] image.w

 [number] image.h

 The width and height (in pixels) of this image.

Image methods
=============

image_new
=========

Image *image_new (int imgtype, int w, int h);
     Creates a new image

image_new_copy
==============

Image *image_new_copy (Image *image);

image_free
==========

void image_free (Image *image);

image_getpixel
==============

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

image_putpixel
==============

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

image_clear
===========

void image_clear (Image *image, int color);

image_copy
==========

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

image_merge
===========

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

image_crop
==========

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

image_hline
===========

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

image_vline
===========

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

image_rect
==========

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

image_rectfill
==============

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

image_line
==========

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

image_ellipse
=============

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

image_ellipsefill
=================

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

image_convert
=============

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

image_count_diff
================

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_new
=========

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

frame_new_copy
==============

Frame *frame_new_copy (Frame *frame);

frame_free
==========

void frame_free (Frame *frame);

frame_is_link
=============

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

frame_set_frpos
===============

void frame_set_frpos (Frame *frame, int frpos);

frame_set_image
===============

void frame_set_image (Frame *frame, int image);

frame_set_position
==================

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

frame_set_opacity
=================

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_new
=========

Layer *layer_new (int imgtype);

layer_set_new
=============

Layer *layer_set_new (void);

layer_new_copy
==============

Layer *layer_new_copy (Layer *layer);

layer_new_with_image
====================

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

layer_free
==========

void layer_free (Layer *layer);

layer_is_image
==============

bool layer_is_image (Layer *layer);

layer_is_set
============

bool layer_is_set (Layer *layer);

layer_get_prev
==============

Layer *layer_get_prev (Layer *layer);

layer_get_next
==============

Layer *layer_get_next (Layer *layer);

layer_set_name
==============

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

layer_set_blend_mode
====================

void layer_set_blend_mode (Layer *layer, int blend_mode);

layer_add_frame
===============

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

layer_remove_frame
==================

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

layer_get_frame
===============

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

layer_add_layer
===============

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

layer_remove_layer
==================

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

layer_move_layer
================

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

layer_render
============

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

layer_flatten
=============

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

Mask
****

mask_new
========

Mask *mask_new (void);

mask_new_copy
=============

Mask *mask_new_copy (Mask *mask);

mask_free
=========

void mask_free (Mask *mask);

mask_is_empty
=============

bool mask_is_empty (Mask *mask);

mask_set_name
=============

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

mask_move
=========

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

mask_none
=========

void mask_none (Mask *mask);

mask_invert
===========

void mask_invert (Mask *mask);

mask_replace
============

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

mask_union
==========

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

mask_subtract
=============

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

mask_intersect
==============

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

mask_merge
==========

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

mask_by_color
=============

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

mask_crop
=========

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

Path
****

path_new
========

Path *path_new (const char *name);

path_free
=========

void path_free (Path *path);

path_set_join
=============

void path_set_join (Path *path, int join);

        * PATH_JOIN_MITER

        * PATH_JOIN_ROUND

        * PATH_JOIN_BEVEL

path_set_cap
============

void path_set_cap (Path *path, int cap);

        * PATH_CAP_BUTT

        * PATH_CAP_ROUND

        * PATH_CAP_SQUARE

path_moveto
===========

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

path_lineto
===========

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

path_curveto
============

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

path_close
==========

void path_close (Path *path);

path_move
=========

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

path_stroke
===========

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

path_fill
=========

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_new
==========

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

sprite_new_copy
===============

Sprite *sprite_new_copy (Sprite *sprite);

sprite_new_flatten_copy
=======================

Sprite *sprite_new_flatten_copy (Sprite *sprite);

sprite_new_with_layer
=====================

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

sprite_free
===========

void sprite_free (Sprite *sprite);

sprite_lock
===========

void sprite_lock (Sprite *sprite);

sprite_unlock
=============

void sprite_unlock (Sprite *sprite);

sprite_is_locked
================

bool sprite_is_locked (Sprite *sprite);

sprite_is_modified
==================

bool sprite_is_modified (Sprite *sprite);

sprite_was_saved
================

void sprite_was_saved (Sprite *sprite);

sprite_set_filename
===================

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

sprite_set_size
===============

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

sprite_set_frames
=================

void sprite_set_frames (Sprite *sprite, int frames);

sprite_set_speed
================

void sprite_set_speed (Sprite *sprite, int speed);

sprite_set_path
===============

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

sprite_set_mask
===============

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

sprite_set_layer
================

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

sprite_set_frpos
================

void sprite_set_frpos (Sprite *sprite, int frpos);

sprite_set_imgtype
==================

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

sprite_add_path
===============

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

sprite_remove_path
==================

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

sprite_add_mask
===============

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

sprite_remove_mask
==================

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

sprite_request_mask
===================

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

sprite_render
=============

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_new
=========

Stock *stock_new (int imgtype);

stock_new_copy
==============

Stock *stock_new_copy (Stock *stock);

stock_free
==========

void stock_free (Stock *stock);

stock_add_image
===============

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

stock_remove_image
==================

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

stock_replace_image
===================

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

stock_get_image
===============

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

Undo
****

undo_new
========

Undo *undo_new (Sprite *sprite);

undo_free
=========

void undo_free (Undo *undo);

undo_enable
===========

void undo_enable (Undo *undo);

undo_disable
============

void undo_disable (Undo *undo);

undo_is_enabled
===============

bool undo_is_enabled (Undo *undo);

undo_is_disabled
================

bool undo_is_disabled (Undo *undo);

undo_can_undo
=============

bool undo_can_undo (Undo *undo);

undo_can_redo
=============

bool undo_can_redo (Undo *undo);

undo_undo
=========

void undo_undo (Undo *undo);

undo_redo
=========

void undo_redo (Undo *undo);

undo_open
=========

void undo_open (Undo *undo);

undo_close
==========

void undo_close (Undo *undo);

undo_image
==========

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

undo_flip
=========

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

undo_add_image
==============

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

undo_remove_image
=================

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

undo_replace_image
==================

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

undo_add_frame
==============

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

undo_remove_frame
=================

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

undo_add_layer
==============

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

undo_remove_layer
=================

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

undo_move_layer
===============

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

undo_set_layer
==============

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

undo_set_mask
=============

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

Effect
******

effect_new
==========

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

effect_free
===========

void effect_free (Effect *effect);

effect_load_target
==================

void effect_load_target (Effect *effect);

effect_set_target
=================

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

effect_set_target_rgb
=====================

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

effect_set_target_grayscale
===========================

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

effect_set_target_indexed
=========================

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

effect_begin
============

void effect_begin (Effect *effect);

effect_begin_for_preview
========================

void effect_begin_for_preview (Effect *effect);

effect_apply_step
=================

int effect_apply_step (Effect *effect);

effect_apply
============

void effect_apply (Effect *effect);

effect_flush
============

void effect_flush (Effect *effect);

effect_apply_to_image
=====================

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

effect_apply_to_target
======================

void effect_apply_to_target (Effect *effect);

ConvMatr
********

convmatr_new
============

ConvMatr *convmatr_new (int w, int h);

convmatr_new_string
===================

ConvMatr *convmatr_new_string (const char *format);

convmatr_free
=============

void convmatr_free (ConvMatr *convmatr);

Convolution Matrix Effect
=========================

set_convmatr
============

void set_convmatr (ConvMatr *convmatr);

get_convmatr
============

ConvMatr *get_convmatr (void);

get_convmatr_by_name
====================

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_new
=========

Curve *curve_new (int type);
     Creates a new curve, type can be CURVE_LINEAR or CURVE_SPLINE.

curve_free
==========

void curve_free (Curve *curve);

curve_add_point
===============

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

curve_remove_point
==================

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

Color Curve Effect
==================

set_color_curve
===============

void set_color_curve (Curve *curve);

CurvePoint
**********

curve_point_new
===============

CurvePoint *curve_point_new (int x, int y);

curve_point_free
================

void curve_point_free (CurvePoint *point);

JEvent
******

JList
*****

JRect
*****

JRect fields
============

        * [number] rect.x

 [number] rect.y

 Position of the upper-left corner of the rectangle.

        * [number] rect.w

 [number] rect.h

 Size of the rectangle (width and height).

JRegion
*******

JWidget
*******

Index
*****