Introduction

Anim8or introduces a scripting language ASL with version 0.95. It is included as part of Anim8or. A scripting language allows you to automate tasks that you do often, to extend Anim8or’s basic functionality with plug-ins, and to animate elements in your scenes more flexibly and quickly.

ASL is an interpreted language loosely based on the C programming language but with a somewhat restricted set of functionality. It also borrows a few simple syntactic constructs from C++. Aspects of ASL that are the same as or similar to those in C use the same syntax. Those that are different generally use unique syntax to reduce the confusion that users familiar with C might have. Finally ASL includes a number of concepts specific to supporting Anim8or.

ASL scripts can be included within an Anim8or project or kept in a source file on disk. Normally disk files will have an extension of .a8s or .txt but any other extension may be used. The .a8s extension is specifically for scripts that will be preloaded when Anim8or starts up. The .txt extension is for scripts that are run from disk when using Anim8or.

This spec is dated February 6, 2007.

Updates to the scripting language for v0.97b dated June 1, 2008 are listed throughout the spec in BLUE.

Kinds of Scripts

ASL has several different types of scripts for various purposes. For example there are scripts that export Objects, those that build and manipulate models, and ones to compute the value of a controller in a Scene. They all use a common language but each has its own requirements and restrictions.

Variables and Names

Variable and function names begin with a letter or an underscore character ‘_’ followed by any number of letters, digits and underscores. Upper case letters are distinct from lower case so that ‘Anim8or’ and ‘anim8or’ are unique names. In addition user declared variables must be preceded by a dollar sign ‘$’ as in ‘$Anim8or’.

Data Types

The types supported by ASL are:

float

A float is a 32 bit floating point value. A float constant is a number with either a decimal point or an exponent or both:

1.234 .7 10. 1e10 3.141e-4

int

An int is a 32-bit signed integer. Constants may be decimal or hexadecimal:

1234 1 0x1234 0xface

string

A string consists of zero or more ASCII characters. Constants are enclosed with double quotes. The backslash character ‘\’ is used as a quote when double quotes are required in a string and to define non-printable characters. They are also used to define new-line characters and tabs as in C. Backslashes within constants must be doubled as well:

"hello"

"This is a string. "

"a double quote \" in a string"

"Line 1.\nLine 2.\n"

The string type has several useful functions.

typedef string {
int length(void);
string SubString(int first, int last);
string Insert(string fStr, int pos);
int GetChar(int pos);
string SetChar(int val, int pos);
string GetDir(void);
string GetRoot(void);
string GetExt(void);
};

The function length() returns the number of characters in a string.

SubString() returns a string composed of the first-th to the last-th characters in a string. Character positions are numbered from 0 to length() – 1. Out of bounds values are clamped to the dimensions of the string; if first is greater than last an empty string is returned.

Insert() inserts another string into a copy of a string before the character at position pos and returns the result. If pos is <= 0 the new string is inserted at the first and if it is >= length() then it is added at the end.

GetChar() returns the value of the character at position pos. If pos is negative or >= length() it returns -1. SetChar() makes a copy of a string and sets the value of the character at position pos in the copy to val. If pos is out of range it does not change the string and returns the copy unaltered.

GetDir(), GetRoot() and GetExt() return the string corresponding to the director, root and extension of a string, respective, assuming that it is a valid name of a file.

point2

The type point2 is a vector of two floating point values. They are similar to the C struct:

typedef struct {
float x, y;
} point2;

Individual floating point values are referenced using member notation:

$myvar.x $myvar.y

Values are defined as a parenthesized list of two integer or floating point values:

(1.0, 7) (0, 0) (3.142, 1.732) ($ii, 7*$p)

point3

Similarly the type point3 is a vector of three floating point values. They are similar to the C struct:

typedef struct {
float x, y, z;
} point3;

Individual floating point values are referenced using member notation:

$myvar.x $myvar.y $myvar.z

Values are defined as a parenthesized list of three integer or floating point values:

(1.0, 7, 9.999) (0, 0, 0) (3.142, 1.732, -1.414)
($loc.x, $loc.y*1.5, 0.0)

quaternion

The type quaternion is a vector of four floating point values. They are used to represents a rotation or orientation in Anim8or.

typedef struct {
float x, y, z, w;
} quaternion;

Individual floating point values are referenced using member notation:

$q0.x $q0.y $q0.z $q0.w

Quaternion values may be constructed from 4 scalar values:

(1.0, 7, 9.999, -1e8) (0, 0, 0, 0)

float4x4

The type float4x4 is a 4 by 4 element array. They are used for things like three dimensional transformations.

file

A file is an ordinary disk for reading or writing. They can only be used in specific kinds of scripts such as import and export plug-in scripts.

Various Anim8or Types

A number of types are used to refer to specific parts of an Anim8or project. Their internal structure is generally hidden. Specific built in functions are used to access and set their values. These functions are described later.

project – An Anim8or project.

object – An Object within an Anim8or project.

figure – A Figure in an Anim8or project.

sequence – A Sequence in an Anim8or project.

scene – A Scene in an anim8or project.

material – A material.

shape – A 3D component in an Object. These include Spheres, Cubes, Meshes, Subdivision Objects, etc.

meshdata – The specific geometry of a shape as represented within Anim8or.

tridata – A simplified version of meshdata that is useful when exporting data.

arrays

Arrays in ASL are much more general than those in C. They are defined with an initial size but it can be increased or reduced by a running script. Elements of an array are referenced in the usual way:

$myarray[10] $colors[$i + 12]

Additionally all arrays contain a struct like predefined member ‘size’:

$myarray.size

Referencing size returns the number of elements that the array currently holds. Assigning a value to size sets the number of elements to that value. When an array’s size is increased in this manner new elements are assigned a value of 0, an empty string, or a null pointer depending on the type of the array. If the size is reduced the higher indexed values are discarded.

There are also two C++ like member functions for arrays pop() and push():

<type> $myarray.pop(void);
int $myarray.push(<type> $value);

pop() removes the last elements from the array and returns it’s value, thus reducing the array’s size by one. push() increases the size of an array by one and sets the value of the last element to it’s parameter. It returns the index of the element pushed.

Predefined Constants

There are several predefined constants in ASL. General constants are listed below. Other values that are only meaningful as parameters to certain functions are listed later with those functions.

int true = 1
int false = 0
float PI = 3.1415926

Variable Declarations

Variables are declared similar to how they are in C. However there are some differences:

- Variables cannot be initialized in the declaration,
- Declaration don’t have to be grouped at the first. They can appear after executable statements,
- There are no scopes. A variable can be used anywhere after it is declared.

int $i, $count;
float $sizes[10]; /* array initially with 10 elements */
shape $mymodel;
float PI = 3.1415926

Expressions

ASL supports many of the operators fond in C.

Function Calls

ASL has a number of built in member and non-member functions. These are described elsewhere in this document. There is currently no support for user defined functions.

Unary Operators

- negation: int, float, point2, point3, quaternion
! not: int, float

Binary Operators

+ addition: int, float, point2, point3
- subtraction: int, float, point2, point3
+ concatenation: string
* multiplication: int, float, point2/3*float,
float*point2/3, quaternion*float
float*quaternion
/ division: int, float
% mod: int
< == <= comparisons: int, float, string;
> != >= returns int with value of 1 or 0
&& logical and: int, float; returns int 1 if both
operands are non-zero
|| logical or: int, float; returns int 1 if either
operand is non-zero

Statements

Expression

An expression is the simplest statement. Normally an expression statement will call a function that has some kind of a side effect such as setting an Objects location. Expression statements that don’t have side effects such as $i + 1 are allowed but aren’t very useful.

Assignment

An assignment statement sets the value of a variable to value of an expression.

Numeric and string types simply copy the value of the expression to the variable:

int, float, string, point2, point3, quaternion,
float4x4

Complex types refer to objects within Anim8or. They are actually handles to the objects, not the actual objects. Assigning a value to a variable of these types doesn’t change the Anim8or project but sets the object referenced by that variable. Member functions in these types are used to alter them.

material, meshdata, tridata, shape, object, figure,
sequence, scene, project

Variable of type file cannot be assigned.

Compound Statement

A compound statement is a list of zero or more statements enclosed in curly braces “{}”. They may be used anywhere a statement may be used:

{
$shape.loc.x = sqrt($val);
$ii = $ii + 1;
}

If Statement

An if statement evaluates a control expression. If the value is non-zero then the <then-statement> is executed next otherwisre the <else-statement> is executed if it is present. The syntax is the same as C’s:

if (<expr>)
<then-statement>
else
<else-statement>

As in C the “else” statement is optional:

if (<expr>)
<then-statement>

While Statement

A while statement evaluates a control expression. If it the value of <expr> is non-zero then it executes its subordinate <statement> and reevaluates the control expression. This continues until the expression evaluates to zero. The syntax is the same as in C:

while (<expr>)
<statement>

For Statement

A for statement evaluates several control expressions and then executes its subordinate statement a number of times based on those values. For statements in ASL are not the same as those in C. The two general forms are:

for <var> = <init> to <limit> do
<statement>

for <var> = <init> to <limit step <step> do
<statement>

<var> can be either an int or float. The value of <init> is assigned to <var> and the values of <limit> and <step> expressions are cast to the type of <var> and saved. If <step> is not present a value of 1 or 1.0 is used. Then the value of <var> is compared to <limit>. If <step> is greater than or equal to zero and <var> is less than or equal to <limit>, or if <step> is less than zero and <var> is greater than or equal to <limit> the <statement> is executed after which <step> is added to <var>. This procedure repeats until the comparison fails.

Special Type Details

The special ASL types are described here.

Project Type

struct project {
object curObject; // The current Object
figure curFigure; // The current Figure
sequence curSequence; // The current Sequence
scene curScene; // The current Scene
int MarkMaterials(int val);
int MarkObjects(int val);
int MarkFigures(int val);
int MarkSequences(int val);
int MarkScenes(int val);
material NewMaterial(string name);
int GetNumMaterials(void);
texture NewTexture(string name);
texture NewCubeMapTexture(string name);
int GetNumTextures(void);
texture GetTexture(int index);
int GetTextureIndex(texture texVar);
texture LookupTexture(string name);
string GetDirectory(int index);
};

The Mark() functions set the mark member of all Materials, Objects, Figures, Sequences and Scenes, respectively, in a project to a value of 1 if val != 0, otherwise to 0. Mark() is useful for keeping track of whether a particular data item has been seen before when a script is exporting or altering a project. This is done by first clearing all marks with Mark(). The components of a project can then be visited in any order. If a component’s mark member is zero it is set to 1 and the component is processed. If mark is already 1 that component can be skipped.

NewMaterial() adds a new global material to the project and returns it. If one already exists with the same name it doesn’t add anything and returns NULL. GetNumMaterials() returns the number of global materials in a project. GetMaterial() returns a specific material. Materials are numbered from 0 to GetNumMaterials() – 1.

NewTexture() adds a new texture object to a project with the given name and returns the texture. NewCubeMapTexture() adds a new cube map texture. If a texture with that name already exists no new texture is created and NULL is returned. GetTexture() returns the texture numbered index, and GetTextureIndex returns the texture index corresponding to it’s parameter. If there is no such texture they return NULL and -1, respectively. LookupTexture() returns the texture with the given name or NULL if no such texture exists.

The function GetDirectory() returns the name of one of the target directories that Anim8or maintains. These are settable in the File->Configure dialog. The names shown below are used to access the different directories. An invalid value returns an empty string.

enum {
DIRECTORY_PROJECT,
DIRECTORY_TEXTURE,
DIRECTORY_IMPORT,
DIRECTORY_IMAGE,
DIRECTORY_SCRIPT
};

GUI Type

struct GUI {
int Xenabled; // A value of 1 means the axis is
int Yenabled; // enabled and 0 disabled
int Zenabled; // The current Sequence
};

The GUI type is used only for a predefined variable GUI. It gives scripts access to certain settings in Anim8or’s interface. Unless stated otherwise you can read and assign its members from within a script. Invalid or out of range values are silently clamped to a valid value or ignored.

Note: The GUI variable is not accessible from invariant scripts such as controller, parameteric plug-in or export plug-in scripts. Such scripts must return consistent results.

Material Type

struct material {
string name; // The current Object
float Ka; // Ambient factor
float Kd; // Diffuse factor
float Ks; // Specular factor
float Ke; // Emissive factor
float alpha; // Transparency 0->1, 1 = opaque
float roughness; // Specular roughness factor
float brilliance; // Brilliance factor
int LockAmbiantDiffuse;
int Marked; // 1 if Marked, 0 if not Marked
point3 ambient; // ambient color
point3 diffuse; // diffuse color
point3 specular; // specular color
point3 emissive; // emissive color
texture GetTexture(int kind);
int SetTexture(int kind, texture tex);
int GetBlendMode(int mode);
int SetBlendMode(int kind, int mode);
int GetAlphaMode(int mode);
int SetAlphaMode(int kind, int mode);
};

The GetTexture() function returns the texture for the specifid kind if the material has one defined. Otherwise it returns NULL. Similarly the SetTexture() function sets the texture for the given kind. If tex is NULL then any currently defined texture of that kind is removed.

The following predefined names are accepted for texture kinds:

enum {
TEXTURE_AMBIENT,
TEXTURE_DIFFUSE,
TEXTURE_SPECULAR,
TEXTURE_EMISSIVE,
TEXTURE_TRANSPARENCY,
TEXTURE_BUMPMAP,
TEXTURE_ENVIRONMENT,
};

These constants are integers and can be used in expressions like any integer constant. The actual values may change in future releases so be sure to use these names in your scripts instead of relying on specific integer values when calling GetTextureName().

The functions SetBlendMode() and GetBlendMode() set and return a particular texture’s blend mode. Similarly the functions SetAlphaMode() and GetAlphaMode() set and return a particular texture’s alpha mode. The following enums correspond to the named modes.

enum BlendMode {
BLEND_MODE_DECAL = 0,
BLEND_MODE_DARKEN = 1,
BLEND_MODE_LIGHTEN = 2,
};

enum AlphaMode {
ALPHA_MODE_NONE = 0,
ALPHA_MODE_LAYER = 1,
ALPHA_MODE_FINAL = 2,
};

Texture Type

struct texture {
string name; // texture’s name
int Marked; // Marked flag, 1 or 0
const int CubeMap; // 1 if a Cube Map, else 0
int InvertImage; // invert image flag, 1 or 0
string GetFileName(void);
string GetCubeMapFileName(int face);
int SetFileName(string name);
int SetCubeMapFileName(string name, int face);
};

Assigning to name changes the name of a texture and all references to it in a material. If another texture already has that name then the assignment is not made and the texture retains its existing name.

GetFileName() and SetFileName() return and set the name of the file used for the texture image. If the texture is a cube map then the functions GetCubeMapFileName() and SetCubeMapFileName() must be used instead. The additional parameter face specifies which faces value to use. Out of range values return null strings. The following predefined names can be used for the faces:

enum CubeMapFace {
FACE_POS_X = 0,
FACE_NEG_X = 1,
FACE_POS_Y = 2,
FACE_NEG_Y = 3,
FACE_POS_Z = 4,
FACE_NEG_Z = 5,
FACE_RIGHT = 0,
FACE_LEFT = 1,
FACE_UP = 2,
FACE_DOWN = 3,
FACE_FRONT = 4,
FACE_BEHIND = 5,
};

Attribute Type

struct attribute {
string GetName(void);        // Return attributes name
int GetType(void);           // Returns attributes type (from table below)
int GetBoolValue(void);      // Value of a Boolean attribute
    int GetIntValue(void);       // Value of an integer attribute
    float GetFloatlValue(void);  // Value of a floating point attribute
point3 GetPoint3Value(void); // Value of a point3 attribute
    quaternion GetQuaternionValue(void); // Value of a quaternion attribute
string GetStringValue(void); // Value of a string attribute
};

Calling a GetXXXValue() function for the a type other than the attributes actual type returns 0.  You should call GetType() prior to querrying an attributes value to verify that it has the expected type.  The following predefined names should be used for the types:

enum AttributeTypes {
ATTR_UNKNOWN = 0,
ATTR_INT = 1,
ATTR_FLOAT = 2,
ATTR_POINT2 = 3,
ATTR_POINT3 = 4,
ATTR_QUATERNION = 5,
ATTR_STRING = 6,
};

Spline Type

struct spline {
float GetLength(void);       // Return the length of the spline
    point3 Eval(float t);        // Value of spline at position t from the start
    point3 GetTangent(float t);  // Tangent (direction) of spline at t
    quaternion Orientation(float t); // Orientation of spline at t
};

You can use Eval() and Orientation() to sample the position and orientation of a spline.  Use the function toFloat4x4() to convert the orientation into a transformation matrix.

Object Type

struct object {
string name; // object’s name
int Selected; // Selected flag, 1 or 0
int Marked; // Marked flag, 1 or 0
material NewMaterial(string name); // Define a new material
int GetNumMaterials(void);
material GetMaterial(int index);
material LookupMaterial(string name);
shape LookupShape(string name);
int GetShapes(shape fshapes[]);
// return array of top level shapes
    int GetNumAttributes(void);
    attribute GetAttribute(int index);
    attribute LookupAttribute(string name);
};

GetNumMaterials() returns the number of materials in an object and GetMaterial() returns the indexth material in the object. Materials are numbered from 0 to GetNumMaterials() - 1. LookUpMaterial() returns a material with the given name of there is one in the object, otherwise it returns NULL.

GetShapes() fills it’s parameter with all of the top level shapes in an Object. A single Group shape is returned for each top level group. Individual shapes in a Group can be accessed from this group with it’s GetShapes() member function. The return value is the number of shapes returned.  LookupShape() returns the shape with the given name if one exists.  Otherwise it returns NULL.

Shape Type

struct shape {
point3 loc; // location relative to parent
quaternion orientation; // relative orientation
string name; // shape’s name
int Selected; // Selected flag, 1 or 0
int Marked; // Marked flag, 1 or 0
int GetKind(void); // return kind of shape
shape ConvertToMesh(void); // convert 3d shape to mesh
shape ConvertToSubdivided(void);
// convert 3d shape to subdivision shape
float4x4 GetGlobalTransform(void); // Transform matrix
float4x4 GetGlobalNormalTransform(void);
// Transform matrix for normals
meshdata GetMeshData(void); // return mesh information
tridata GetTriangleData(void);
// return triangular representation of shape
};

GetKind() returns the type of shape it represents. The values returned are:

enum {
SHAPE_KIND_UNKNOWN,
SHAPE_KIND_SPHERE,
SHAPE_KIND_RECT_SOLID,
SHAPE_KIND_MESH,
SHAPE_KIND_CYLINDER,
SHAPE_KIND_PATH,
SHAPE_KIND_TEXT,
SHAPE_KIND_MODIFIER,
SHAPE_KIND_SUBDIVISION,
SHAPE_KIND_IMAGE,
SHAPE_KIND_PARAM_PLUGIN,
SHAPE_KIND_GROUP,
SHAPE_KIND_NAMED,
};

SHAPE_KIND_NAMED is used to refer to Objects from a Figure or a Scene.

GetMeshData() returns a structure with the description of the faces and materials defined by the shape. The meshdata structure holds the basic data used by Anim8or for a Mesh. Other shapes such as parameteric shapes create meshdata structures for Anim8or when it needs to display them. Each point is uniquely stored in this format. Points used in multiple faces may use different normals or texture coordinates.

GetTriangleData() returns a tridata structure. This is a simplified representation of what is stored in a meshdata struct. It consists of triangles built from uniforms arrays of geometry, texture coordinates, normals, etc. Points from a shape that are used in multiple faces with different normals or texture coordinates are duplicated. This representation is suitable for direct rendering as vertex arrays in OpenGL or D3D.

GetGlobalTransform() returns a matrix that transforms the points in a tridata variable to their location in the world view.

The following types are subclasses of the shape type. They have all of the members that shape has plus the additional ones shown. If you are unsure about it, you should check that a shape is the appropriate kind with GetKind() before accessing these specialized members it it will cause an error.

Cube Type

struct cube : shape {
float xsize; // x dimension
float ysize; // y dimension
float zsize; // z dimension
int xdivisions;
int ydivisions;
int zdivisions;
};

Variable members like xsize can be both read and assigned. If assigned an out of range value it is silently clamped to the supported range.

Sphere Type

struct sphere : shape {
float diameter;
int lat; // number of faces in latitude
int lon; // and longitude
};

Cylilnder Type

struct cylinder : shape {
float length;
float startdiameter;
float enddiameter;
int lat; // number of faces in latitude
int lon; // and longitude
int CapStart; // 1 = cap start end, 0 = don’t
int CapEnd; // 1 = cap final end, 0 = don’t
};

Mesh and Meshdata Types

The mesh and meshdata types are similar but not entirely equivalent. mesh is a subclass of shape which contains a mesh or subdivision shape. It is entirely editable and can have points, textue coordinates, materials etc. added, deleted or modified. is not the same as a mesh shape. meshdata is a read-only view of any 3d shape.

The meshdata type, on the other hand, is a read-only copy of an arbitrary 3D shape. It is used in scripts for exporting shapes and internally by Anim8or for drawing. Parameteric shapes such as spheres create meshdata objects when Anim8or need to draw them, for example.

There are some functions common to the two types that return internal values, and some functions found only in the mesh type that can modify it. Finally there are some functions found in both types that select and mark individual points, edges and faces that are useful for recording which parts have been processed but don’t really change anything in them.

Mesh Members

The following functions in the mesh type are used to add, delete and change specific values:

struct mesh : shape {
float smoothangle;
int Open(void); // Open a mesh for editing
int Close(void); // Finish editing a mesh

int GetIsNew(void); // True when a plug-in is first built
// Adding points, texture coordinates, faces, etc.:

int AddPoint(point3 loc);
int AddTexCoord(point2 uv);
int OpenFace(int matNo, int flags);
int CloseFace(void);
int VertexN(int index);
int TexCoordN(int index);
int AddMaterial(material mat);

// Mesh altering functions:

int SetPoint (int index, point3 val);
int SetTexCoord(int index, point2 val);
int SetMaterial(int index, material mat);

// Point, edge and face value sets:

int SetFacePointIndex(int faceIndex, int vtxIndex,
int index);
int SetFaceTexCoordIndex(int faceIndex, int vtxIndex,
int index);
int SetFaceMaterialIndex(int faceIndex, int matIndex);
int SetEdgeSharpness(int edgeIndex, int val);

int SetFaceHasTexCoords(int index, int val);

// Delete functions:

    int DeletePoint(int pointIndex);
    int DeleteEdge(int edgeIndex);
    int DeleteFace(int faceIndex);
    int DeleteSelectedPoints(void);
    int DeleteSelectedEdges(void);
    int DeleteSelectedFaces(void);
    int DeleteMarkedPoints(void);
    int DeleteMarkedEdges(void);
    int DeleteMarkedFaces(void);

// Data clean-up:

int RemoveUnusedTexCoords(void);
int RemoveUnusedNormals(void);
int RemoveUnusedBinormals(void);
int RemoveUnusedMaterials(void);
int RemoveUnusedData(void);
};

Meshes and subdivision shapes can be edited to add new points, faces, etc. A call to Open() enables editing. Once editing is complete Close() should be called to flush any unsynchronized data to the actual shape. These two functions return 1 if they succeed and 0 if they fail. Attempting to open a mesh that is already open or a shape that isn’t a mesh or subdivision object will fail. Similarly calling Close() on an unopened mesh will fail.

AddPoint() and AddTexCoord() add new vertices and texture coordinates to a mesh. The return value is an integer index that is used to refer to the new point or texture coordinate when adding new faces. AddMaterial() adds a new material to the Mesh and returns it’s index.

OpenFace() begins the definition of a new face. It returns the index of the newly created face. If an error occurs it returns 0 and no new face is added. The parameter matNo sets the face’s material. It is a zero based index into the mesh’s materials. The bit vector flags specifies the additional properties the face will have. A value of FACE_HAS_TEXCOORDS specifies that the face will have texture coordinates. All other bits are ignored.

GetIsNew() returns true the when a plug in mesh is first created, otherwise false. This allows a script to do one time initializations of materials and to preserve any material set by the user on subsequent calls.

VertexN() adds a new point to a face. index is the value returned by a call to AddPoint(). The return value is index if the call succeeds. If it fails the return value is -1. A call will fail if the value of index is not a valid point index for this mesh. VertexN() must be called after all other properties for a point have been set such as those set by a call to TexCoordN().

TexCoordN() sets the texture coordinate for the current point. index is the value returned by a call to AddTexCoord(). The return value is index if the call succeeds. If it fails the return value is -1. A call will fail if the value of index is not a valid texture coordinate index for this mesh.

CloseFace() must be called after a face is defined to complete the definition.

SetPoint(), SetTexCoord() and SetMaterial() change the values of the point, texture coordinate or material indicated by the index parameter. This has the effect of moving a point, changing a texture coordinate, and changing a material for all faces in that mesh that currently use that value. The functions like SetFacePointIndex() however change the index number for a particular point in face number faceIndex. Other faces that used the same original point are not altered.

SetEdgeSharpness() sets the subdivision sharpness for an edge in the mesh. The edge will stay creased through this number of subdivisions. The sharpness can have a value of 0 to 7 where 0 is smooth and 7 is maximally creased.

SetFaceHasTexcoords() sets or clears the use of texture coordinates by this face. It returns the previous setting.

DeletePoint(), DeleteEdge() and DeleteFace() delete the point, edge and face corresponding to the value of the parameter.  They return 1 if it was deleted, else 0 if it doesn't exist.  DeleteSelectedPoints/Edges/Faces() and DeleteMarkedPoints/Edges/Faces() delete and selected and marked component of that kind in a mesh.  The return the number of things deleted.  Note: after something is deleted the remaining components are renumbered.   Thus if you have saves the index of a point in a variable it may no longer refer th the same point, or any valid point.

There are several functions that remove unused data from a mesh. They can reduce the amount of storage required for a mesh after it’s geometry has been edited. They don’t delete any points or edges. What they do is remove unused auxiliary data that is not references by any geometry in the mesh such as texture coordinates or normals. RemoveUnusedTexCoords() removes unreferenced texture coordinates, for example. Note that RemoveUnusedMaterials() doesn’t delete any materials from an object but it does remove unreferenced materials from a mesh’s material table.

Note: Most mesh member functions cannot be applied to non-mesh shapes because the geometry of parameteric shapes in cannot be directly edited. However SetMaterial() can be applied to material index 0, the default material.

Mesh and Meshdata Members

The following functions in the mesh and meshdata types are used to access internal values:

struct mesh : shape { and struct meshdata {

// Metric queries:

int GetNumPoints(void);
int GetNumNormals(void);
int GetNumTexCoords(void);
int GetNumBinormals(void);
int GetNumMaterials(void);
int GetNumFaces(void);
int GetNumEdges(void);

// Value queries:

point3 GetPoint(int index);
point3 GetNormal(int index);
point2 GetTexCoord(int index);
point3 GetBinormal(int index);
material GetMaterial(int index);

// Face metric queries:

int GetNumSides(int faceIndex);
int GetFaceHasNormals(int faceIndex); add
int GetFaceHasTexCoords(int faceIndex); add
int GetFaceHasBinormals(int faceIndex); add

// Point, edge and face value queries:

int GetFacePointIndex(int faceIndex, int vtxIndex);
int GetFaceNormalIndex(int faceIndex, int vtxIndex);
int GetFaceTexCoordIndex(int faceIndex, int vtxIndex);
int GetFaceBinormalIndex(int faceIndex, int vtxIndex);
int GetFaceMaterialIndex(int faceIndex);

int GetEdgeIndex(int faceIndex, int index);
int GetEdgeSharpness(int faceIndex);
point3 GetEdgePoint0(int edgeIndex);
    point3 GetEdgePoint1(int edgeIndex);
    int GetEdgeIndex0(int edgeIndex);
    int GetEdgeIndex1(int edgeIndex);
};

Mesh metric queries return the number of items of that kind in the mesh. The corresponding data value queries get the value of a particular one. GetNumPoints() returns the number of points, for example, and GetPoint() returns a specific point. Points, normals, binormals, texture coordinates and materials are zero based arrays. Thus the valid index for a point is 0 to GetNumPoints()-1.

Note: Edges are stored in a one based array however so valid indices for the edges in a mesh are 1 to GetNumFaceEdges(). There is no edge number 0.

Face data queries return the parameters for a particular point or edge of a face. The first parameter is the face index and the second parameter is the point or edge index. The second parameter in an index into the 0 based array of points or edges and should have a value of 0 to GetNumSides()-1.. GetNumSides() returns the number of sides or edges.

GetNumEdges()returns the number of edges in a mesh.  Edges are numbered from 1 to N. GetEdgeIndex() returns the index of a particular edge in a face. The value returned can be positive or negative. If it is negative the edge is reversed when the face is viewed with the vertices in a clockwise orientation.  GetEdgePoint0() and GetEdgePoint1() return the point for the beginning and ending points for an edge.  GetEdgeIndex0() and GetEdgeIndex1() return the point index for the beginning and ending points for an edge.

The GetFaceHas() functions return true (1) or false (0) depending on whether the face has that particular property or not. For example GetFaceHasNormals() returns true if normal data is defined for the face.

The face value query functions return negative values when any of their arguments are out of range with the exception of GetEdgeIndex which returns 0.

Mesh and Meshdata Selection and Marking Members

The following functions in the mesh and meshdata types are used to mark and select individual points, edges and faces:

struct mesh : shape { and struct meshdata {

// Deselect or demark all points, edges or faces.
// Returns count of components cleared:

int DeselectPoints(void);
int DeselectEdges(void);
int DeselectFaces(void);
int DemarkPoints(void);
int DemarkEdges(void);
int DemarkFaces(void);

// Test individual points, edges or faces for mark or selection:

int GetPointSelected(int index);
int GetEdgeSelected(int index);
int GetFaceSelected(int index);
int GetPointMarked(int index);
int GetEdgeMarked(int index);
int GetFaceMarked(int index);

// Set or clear point, edge or face’s selection or marking.
// Returns previous value:

int SetPointSelected(int index, int val);
int SetEdgeSelected(int index, int val);
int SetFaceSelected(int index, int val);
int SetPointMarked(int index, int val);
int SetEdgeMarked(int index, int val);
int SetFaceMarked(int index, int val);
}

Each individual point, edge and face may be marked and selected. Selected parts are often visible in the working views. The selected property is the same thing that is set when you select individual points, edges and faces when editing a mesh. The marked property is a temporary setting that is never visible. It is used throughout Anim8or to keep track of what parts of a mesh have been examined or altered during internal operations. Scripts can use these same properties when they examine any modify meshes as well. The marked property is transitory after a script has run. The selected property is preserved for mesh shapes but not for meshdata objects since meshdata objects are copies of the geometry of a shape, not the actual geometry.

The GetXXXSelected() and GetXXXMarked() functions test whether a particular point, edge or face in a mesh is selected and marked, respectively. The corresponding SetXXXSelected() and SetXXXMarked() set the respective selected and marked properties and return the original values. Finally the DeselectXXX() and DemarkXXX() functions clear all of the selections and markings for their respective kind of components.

Together these functions are useful when processing a mesh for export or modification.

Tridata Type

struct tridata {

// Tridata metric queries:

int GetNumPoints(void);
int GetNumTriangles(void);
int GetNumMaterials(void);

// Tridata value queries:

point3 GetPoint(int index);
point3 GetNormal(int index);
point2 GetTexCoord(int index);
int GetIndex(int index);
int GetMatIndex(int index);
material GetMaterial(int index);
};

The tridata type is basically a set of array of data representing the points it a mesh. GetNumPoints() returns the total number of unique points, normals and texture coordinates it has. GetNumTriangles() returns the number of triangles, and GetNumMaterials() the number of materials.

The data for a particular triangle is indicated by three consecutive values in The number of points is not necessarily three times the number of triangles since points in GetIndex(). To find the data for triangle N (where 0 <= N < num triangles) call GetIndex with 3*N, 3*N+1 and 3*N+2. The return values are passed to GetPoint() to find the value of the three vertices. The following code shows reads the data for triangle N:

tridata $tdata;
int $N, $index1, $index2, $index3;
point3 $p1, $p2, $p3;

$index1 = $tdata.GetIndex($N*3);
$index2 = $tdata.GetIndex($N*3 + 1);
$index3 = $tdata.GetIndex($N*3 + 2);
$p1 = $tdata.GetPoint($N*3);
$p2 = $tdata.GetPoint($N*3 + 1);
$p3 = $tdata.GetPoint($N*3 + 2);
/* The values of $p1, $p2 and $p3 define triangle $N */

Float4x4 Type

struct float4x4 {
private:
float mat[4][4];
// Transform matrix – not accessible to scripts.
public:
point3 Project(point3 p0); // Transform point by mat

};

Predefined Variables

There are several predefined variables in ASL.

project project;

The current project is kept in the variable project.

GUI GUI;

The graphical user interface settings are accessible through the variable