@#
@# Documentation about how to program scripts with ASE
@#
@document_title=ASE Scripting Manual
@html_footer=Back to contents
@rtfh=ASE - Scripting
@$\input texinfo
@$@documentlanguage es
@$@setfilename script.info
@$@settitle ASE Scripting Manual
@$@setchapternewpage odd
@$@paragraphindent 0
@$@setchapternewpage off
@# This should remain commented at the moment (dvi output) @$@finalout
@$
@$@ifinfo
@$This is the Info version of the ASE Scripting manual
@$
@$By David A. Capello
@$@end ifinfo
@$
@$@node Top, , (dir), (dir)
@titlepage
@<pre>
@!indent

                    ASE Scripting 0.6

                 By <a href="http://www.davidcapello.com.ar/">David A. Capello</a>, 2005.

@indent
@</pre>


#include &ltstd_disclaimer.h&gt
<blockquote class="text"><i>
   "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."
</i></blockquote>
@!titlepage


@!text
@heading
Contents

@contents



@text
@text
@heading
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 <a href="lua-5.0.pdf">lua-5.0.pdf</a>. Also, you
  need a text editor to write Lua scripts (the Windows Notepad can
  be used).

@hnode Warning about Lua

  You should known that ASE uses a patched version of Lua, where you
  can use the != operator instead of ~=
<codeblock>
    if current_sprite != nil then
      -- we can use the current_sprite variable...
    end
<endblock>


@heading
Basic Lua Programming

@hnode Comments

  Comments start with --
<codeblock>
    -- this line will be never parsed
<endblock>
  Or you can comment multiple lines
<codeblock>
    --[[
    blah blah blah...
    ]]--
<endblock>
@hnode Example 1
<codeblock>
    local a = 4
    local b = 5
    print ("a+b is: " .. (a+b))
<endblock>

  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:
<textblock>
    a+b is: 9
<endblock>
  Also we could use:
<codeblock>
    print (a.."+"..b.." is: "..(a+b))
<endblock>
  To print:
<textblock>
    4+5 is: 9
<endblock>
@hnode Example 2
<codeblock>
    function add (a, b)
      return a+b
    end
    print ("1+2 = " .. add (1, 2))
<endblock>
  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.

@hnode Example 3
<codeblock>
    for c = 1, 10 do
      print (c)
    end
<endblock>
  This repeat the block between the "do" keyword and the "end" keyword
  10 times (from 1 to 10 inclusive).

  So this print:
<textblock>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
<endblock>
@hnode Example 4
<codeblock>
    for c = 1, 10 do
      if c == 5 then
        break
      end
      print (c)
    end
<endblock>
  In this case when "c" come to 5 the for is breaked so the other
  iterations aren't made.  This print:
<textblock>
    1
    2
    3
    4
<endblock>
@hnode Example 5
<codeblock>
    for c = 1, 5 do
      if c != 3 then
        print ("c isn't 3 (c is " .. c .. ")")
      else
        print ("c is 3")
      end
    end
<endblock>
  The != operator means "not equal" (negation of equality).  You can
  use the original Lua operator ~= too.

  This print:
<textblock>
    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)
<endblock>
@hnode Example 6
<codeblock>
    local done = false
    local a = 1
    while not done do
      print (a)
      if a == 3 then
      	done = true
      end
      a = a + 1
    end
<endblock>
  This print:
<textblock>
    1
    2
    3
<endblock>
  And can be implemented in this way too:
<codeblock>
    local a = 1
    while a &lt= 3 do
      print (a)
      a = a + 1
    end
<endblock>


@heading
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.

@hnode 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:
@tallbullets
<ul><li>
    R: Red.
<li>
    G: Green.
<li>
    B: Blue.
<li>
    A: Alpha (transparency or opacity).
</ul>
  (0,0,0,0) is mask color, (0,0,0,255) is black, and (255,255,255,255)
  is white.

@hnode IMAGE_GRAYSCALE

  The image has two channels (two bytes) per pixel.
@tallbullets
<ul><li>
    K: Luminance (or black channel)
<li>
    A: Alpha (transparency or opacity).
</ul>
  (0,0) is mask color, (0,255) is black, (255,255) is white.

@hnode IMAGE_INDEXED

  Image uses one byte per pixel:
@tallbullets
<ul><li>
    Index: index of the color that we must use from the color-palette.
</ul>

  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.

@hnode 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.



@heading
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.



@heading
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.



@heading
Math routines

@hnode Constants

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

@hnode Routines

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

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

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

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

@@double @log (double x);
@xref exp, log10
  Returns the natural logarithm of x.

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

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

@@double @sqrt (double x);
@xref hypot, pow
  Returns the non-negative square root of x.

@@double @hypot (double x, double y);
@xref sqrt
  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.

@@double @cos (double x);
@xref sin, tan, acos
  Returns the cosine of x, where x is given in radians.

@@double @sin (double x);
@xref cos, tan, asin
  Returns the sine of x, where x is given in radians.

@@double @tan (double x);
@xref cos, sin, atan
  Returns the tangent of x, where x is given in radians.

@@double @acos (double x);
@xref cos
  Returns the arc cosine in radians and the value is mathematically
  defined to be between 0 and PI (inclusive).

@@double @asin (double x);
@xref sin
  Returns the arc sine in radians and the value is mathematically
  defined to be between -PI/2 and PI/2 (inclusive).

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

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

@@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).



@heading
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.
  


@heading
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:
@tallbullets
<ul><li>
  Graphics objects: Image, Frame, Layer, Mask, Path, Sprite, Stock, Undo.
<li>
  Effect objects: Effect, ConvMatr, Curve, CurvePoint.
<li>
  GUI objects: JEvent, JList, JRect, JRegion, JWidget.
</ul>


@heading
Image

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

@hnode Image fields
<ul><li>
  [number] image.imgtype<br>
    See sprite.imgtype
<li>
  [number] image.w<br>
  [number] image.h<br>
    The width and height (in pixels) of this image.
</ul>
@hnode 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);



@heading
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);



@heading
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);



@heading
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);



@heading
Path

@@Path *@path_new (const char *name);

@@void @path_free (Path *path);

@@void @path_set_join (Path *path, int join);
@tallbullets
<ul><li>
  PATH_JOIN_MITER<br>
<li>
  PATH_JOIN_ROUND<br>
<li>
  PATH_JOIN_BEVEL<br>
</ul>

@@void @path_set_cap (Path *path, int cap);
@tallbullets
<ul><li>
  PATH_CAP_BUTT<br>
<li>
  PATH_CAP_ROUND<br>
<li>
  PATH_CAP_SQUARE<br>
</ul>

@@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);



@heading
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);

@@bool @sprite_is_associated_to_file (Sprite *sprite);

@@void @sprite_mark_as_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);



@heading
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);



@heading
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);



@heading
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);



@heading
ConvMatr

@@ConvMatr *@convmatr_new (int w, int h);

@@ConvMatr *@convmatr_new_string (const char *format);

@@void @convmatr_free (ConvMatr *convmatr);

@hnode Convolution Matrix Effect

@@void @set_convmatr (ConvMatr *convmatr);

@@ConvMatr *@get_convmatr (void);

@@ConvMatr *@get_convmatr_by_name (const char *name);



@heading
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);

@hnode Color Curve Effect

@@void @set_color_curve (Curve *curve);



@heading
CurvePoint

@@CurvePoint *@curve_point_new (int x, int y);

@@void @curve_point_free (CurvePoint *point);



@heading
JEvent



@heading
JList



@heading
JRect

@hnode JRect fields
<ul><li>
  [number] rect.x<br>
  [number] rect.y<br>
    Position of the upper-left corner of the rectangle.
<li>
  [number] rect.w<br>
  [number] rect.h<br>
    Size of the rectangle (width and height).
</ul>



@heading
JRegion



@heading
JWidget



@!text
@$@ifinfo
@headingnocontent
Index

@index
@$@end ifinfo

@$@contents
@$@bye

@text