3 Skill levels

Introduction
The name of the game with Alambik Script is to create audiovisual content which appears exactly the way you want it. Such content can be displayed in a web browser like Internet Explorer, in a special window, in full screen mode, or in Alambik's own MC Player.

Although Alambik Script is a powerful audiovisual tool, it's also surprisingly easy to use.

All of Alambik's commands are natural and easy to remember. This comes from the fact that Alambik Script is a high-level language, based on English and employing a clear and logical syntax. To display a bitmap image, for example, the command picture.display, followed by a few simple parameters, is all you need to use. The same simplicity applies for 3D objects (mesh.display), and so on. It's that easy -- all the commands you need for crafting powerful scripts can be memorized and put to use with minimal practice.

Alambik Script addresses the needs of a large pool of users, consisting of different groups with varying levels of experience. People who use Alambik include seasoned programmers, less programming-savvy graphic artists, musicians, and marketing professionals, along with a whole range of others. To make audiovisual scripting quickly accessible to all, Alambik's instructions come in a range of difficulty levels. We have grouped our programming instructions into the following three categories:

1. Basic instructions
2. Advanced instructions
3. Expert instructions

We invite you to pick and choose from all of these categories, selecting the instructions which best match your needs and skill level.


Basic instructions : Modify and display
1.1 - Displaying an Alambik object

Basic syntax is designed to make programming as simple as possible. All basic instructions are actually concatenations (i.e., several instructions rolled together in one) based on advanced syntax instructions. This helps to reduce the total set of instructions you need to know when scripting.

Basic instructions are ideal for beginning users, but can also be powerful tools for advanced programmers. This is because they let you create applications quickly in situations where optimization is not a priority.

To give an example of the simplicity of basic syntax, let's say you want to display an image named sky.jpg at the center of the screen. To do this you write:

picture.display ("sky.jpg",CENTER,CENTER)

That's all there is to it!

1.2 - Changing the characteristics of Alambik objects

Through basic syntax, you can modify the characteristics of Alambik objects by means of two kinds of instructions (note: most ".set" instructions, which require an objectID, do not fall under the basic syntax category). These two basic syntax instructions for modifying objects are as follows:

1.2.1 - ".select" instructions

".select" instructions let you specify a characteristic or setting that will apply to all objects up until the next ".select" is invoked. ".select" instructions never use ObjectIDs. For example:

pixel.color.select (COLOR_RED)
pixel.display (320,02)
pixel.display (30,102)
pixel.color.select (COLOR_GREEN)
pixel.display (320,10)
pixel.display (32,02)

Here, the first two pixels will be displayed in red, then the next two in green.

1.2.2 ".stack" instructions

".stack" instructions, also used to modify objects, affect only subsequent display instructions. For example:

Picture.resize.stack (320,200)
Picture.display ("sky.jpg",0,0)

In this case, the size of the image sky.jpg will be changed to 320 x 200 pixels, then displayed in its new size at position 0,0 (i.e. at the top left corner of the screen).

NOTES:

• A ".stack" instruction will affect only the subsequent display instruction for any bitmap AVO (Picture, Icon, Pattern, Panel, Button, Mouse, Sprite, or Text). Thus, in the following example, the icon will be resized, but not the picture.

Picture.resize.stack (320,200)
Icon.display ("Man.gif",0,0)
Picture.display ("sky.jpg",50,100)

• Several ".stack" instructions can be combined together. All of them will affect the next object to be displayed. For example, the following instructions will resize and at the same time blur the image sky.jpg :

Picture.resize.stack (320,200)
Picture.blur.stack (50)
Picture.display ("sky.jpg",0,0)

Advanced instructions : Load, modify, display and manipulate
Advanced instructions let you be more creative by introducing the notion of "plug-and-play" objects. Plug-and-play objects are ready to use right after creation and require no special customization (for example, once you create a camera or a viewport, you don't need to give any more information or write extra instructions in order to begin using the object right away).

The one exception to this rule arises if you want to animate plug-and-play objects. To do this, you need to specify additional information (such as tracks and movement) using the Alambik keyframer.

2.1 - Displaying an Alambik Object using an objectID

2.1.1: General Case:

More powerful than basic syntax, advanced syntax instructions let you manipulate objects using ObjectIDs. an objectID is essentially a numeric variable which isn't meant to be used for normal operations (like adding, subtracting, etc.). Instead, ObjectIDs are special names which represent Alambik objects and let you manipulate them during a script's runtime.

The use of ObjectIDs allows Alambik objects to be readily created and manipulated -- even relatively complex objects like 3D primitives, videos, and sprites.

As an example, let's say you want to display the image "sky.jpg" again, this time using an objectID. To display it in the center of the screen with advanced syntax, you would write:

@picture = picture.load ("sky.jpg")
picture.display (@picture, CENTER, CENTER)

Here, @picture is the ObjectID for the image "sky.jpg."

In Alambik, any object can be represented by an objectID. When we write:

@ObjectID = object.load ('Filename')

Filename represents the path (always written in quotes) of whichever object we want to load into memory;

Object stands for the type of object we want to load; and @ObjectID is the name we're giving to this object. You can choose any name you wish for an objectID. It's always best, however, to use a meaningful name which best represents the kind of object you're identifying. By convention, ObjectID names must always be preceded by a @ identifier.

2.1.1: Starting out with real-time 3D:

In order to create striking, real-time 3D environments with Alambik Script, it's necessary first of all to attain an understanding of some basic 3D concepts (see glossary).

Here again, although Alambik's real-time 3D software engine is complete and powerful, it includes easy instructions that let users with little or no 3D knowledge get started right away.

Note: although beginner-level 3D scripting is remarkably easy, we have chosen not to introduce it until now since it requires the use of ObjectIDs.

Alambik 3D worlds (consisting of primitives, meshes, scenes, etc) can be created, displayed and manipulated using instructions which fall into three categories:

1. 3D for beginners
2. Advanced 3D
3. Expert 3D (presented later with the expert instructions).


2.1.1.1: 3D for Beginners:

Even if you're new to 3D, you can get started right away. Alambik lets you display and animate some impressive-looking 3D primitives (Cubes, Spheres, Cylinders, Tubes, Toruses, Quads, Disks, and Rings) using simple instructions.

3D primitives get displayed as if they were 2D objects. In fact, you will be given control over a 2D area of the screen (called the "viewport" in 3D jargon) in which all 3D primitives will be displayed. For example, writing:

mesh.cube.display (CENTER,CENTER,200,200, NULL)

will display a cube in a 200 x 200 pixel area (the viewport) located in the center of your screen.

You may also easily apply a texture to enhance the appearance of your 3D primitive. For example:

mesh.cube.display (CENTER,CENTER,200,200, "texture.jpg", NULL)


Finally, you can animate the 3D primitive using a track: For example:

@track=track.create(TRACK_LOOP_SMOOTH)
    track.key.set(0)
    track.key.rotation.set(0,0,0)
    track.key.set(5)
    track.key.rotation.set(-360,360,720)
track.end()
mesh.cube.display (CENTER,CENTER,200,200, "texture.jpg", @track)

2.1.1.2: Advanced 3D :

Advanced 3D instructions give you the ability to modify, load, display, and manipulate 3D meshes within scenes.

Meshes (stored as files with the ".msh" extention) and scenes (".scn") get loaded from the Alambik AVO Library.

You may also create meshes (as well as scenes) using 3Dstudio Max versions 3 or 4. Such meshes can then be imported into Alambik using ALEX (short for the Alambik Exporter).

With advanced 3D instructions you can create 3D primitives (Cubes, Spheres, Hemispheres, Cylinders, Tubes, Toruses, Quads, Disks, Grids, Billboards, and Rings).

Unlike 3D for beginners, however, you can access these primitives using ObjectIDs. For example, to create and display a cube primitive, you could use an objectID called @cube:

@cube=mesh.cube.create(100)
mesh.display (@cube, 10,10,10)

Once a primitive is created in this manner, you can then modify it, add texture (using a material), animate it, etc.:

@track=track.create(TRACK_LOOP_SMOOTH)
    track.key.set(0)
    track.key.rotation.set(0,0,0)
    track.key.set(5)
    track.key.rotation.set(-360,360,720)
track.end()

@cam = camera.create(0.0, 0.0, -450.0, 0.0, 0.0, 0.0)
@vp = viewport.create()

@picture=picture.load("sky.jpg")
@cube=mesh.cube.create (100)
@material=material.create()
material.texture.set(@material, MATERIAL_DIFFUSETEXTURE, @picture)
mesh.material.set(@cube, @material, MATERIAL_FRONTSIDE)
sequence.play(@track, @cube)


Those who know 3D will find at their disposal all the familiar objects for crafting and manipulating realistic worlds, such as materials, cameras, lights, etc.

2.2 - Changing the characteristics of Alambik Objects


Using advanced syntax, the characteristics of Alambik objects can be modified by means of three kinds of instructions: ".set" ".select" and ".stack."


2.2.1 ".set" instructions

".set" instructions are applied directly to objects and take action immediately.

@sprite = sprite.load ("sky.spr")
sprite.display.set (@sprite, 0,0)
sprite.position.set (@sprite, 100,100)

This series of instructions, for example, immediately changes the position of a sprite. The sprite will no longer be displayed at position 0,0 but instead at 100,100.


2.2.2 - ".select" instructions

".select" instructions let you specify a mode or setting for all objects up until the next ".select" is invoked. In the following example, the text will first be displayed in red, then in green.

text.color.select (COLOR_RED)
@text = text.create ("hello world")
text.display (@text,10,10)
text.color.select (COLOR_GREEN)
text.display (@text,10,30)

2.2.3 ".stack" instructions

".stack" instructions are used to modify objects. Unlike ".set" instructions (which act right away), ".stack" instructions affect only the subsequent display of an object. For example:

@picture = picture.load ("sky.jpg")
picture.resize.stack (320,200)
picture.display (@picture,0,0)

In this case, the size of the image sky.jpg will be changed to 320 x 200 pixels, then displayed in its new size at position 0,0 (i.e. the top left corner of the screen).

NOTES:

• A ".stack" instruction will affect the subsequent display instruction for any bitmap AVO (Picture, Icon, Pattern, Panel, Button, Mouse, Sprite, Text). Thus, in the following example, the icon will be resized, but not the picture.

@picture = picture.load ("sky.jpg")
@icon = icon.load ("man.gif")
picture.resize.stack (320,200)
icon.display ("@icon",0,0)
picture.display (@picture,50,100)

• Several ".Stack" instructions can be combined together. All of them will affect the next object to be displayed. For example, the following instructions can be used to resize and rotate the image sky.jpg :


@picture = picture.load ("sky.jpg")
picture.resize.stack (320,200)
picture.rotation.stack (90, 10,10)
picture.display (@picture,0,0)


Expert instructions : Create, modify, load, display and manipulate.
The expert level introduces instructions which enable you to dynamically create:

3.1. Bitmap Objects.
3.2. Meshes (expert 3D).

By combining such commands with mathematical and conditional instructions, coupled with a clear understanding of the audiovisual environment (3D spaces, etc), you harness the full power of Alambik Script.

In expert level, the characteristics of Alambik objects can be modified by means of three kinds of ".set" ".select" and ".stack" instructions.

3.1 Dynamic creation of a bitmap:

By using the instructions picture.create and icon.create, coupled with a virtual screen and 2D graphics primitives, you can create beautiful bitmaps which never have to be downloaded.

The virtual screen uses the instruction screen.set () to designate a bitmap image, which then becomes the target for all graphic display until the instruction "screen.end" is called.

For example, let's say you want to create a bitmap representing a red-filled circle fitting perfectly inside a green wireframe square:


@picture=picture.create(320,240)
screen.set(@picture)
    box.color.select (0,255,0)
    box.display(CENTER,CENTER,100,100)
    circle.fill.select (VECTOR_SOLID)
    circle.color.select(255,0,0)
    circle.display(CENTER,CENTER, 50)
screen.End()

3.2. Expert Real-Time 3D:

3.2.1. Procedural texture generation:

Dynamic texture generation uses dynamic bitmap creation to create bitmaps which function as textures. For example:

@picture=picture.create(320,240)
screen.set(@picture)
    box.color.select (0,255,0)
    box.display(CENTER,CENTER,100,100)
    circle.fill.select (VECTOR_SOLID)
    circle.color.select(255,0,0)
    circle.display(CENTER,CENTER, 50)
screen.end()
@cube=mesh.cube.create (100)
@material=material.create()
material.texture.set(@material, MATERIAL_DIFFUSETEXTURE, @picture)
mesh.material.set(@cube, @material, MATERIAL_FRONTSIDE)

3.2.2. Dynamic Creation of 3D Meshes.

Alambik Script allows you to create your own meshes by setting each vertex. For example, in the following example you will create and animate a cube (consisting of 8 vertices) :

@Seq =track.create(TRACK_LOOP_SMOOTH)
    track.key.set(0)
    track.key.rotation.set(0,0,0)
    track.key.set(5)
    track.key.rotation.set(-360,360,720)
Track.end()
@cam = camera.create(0.0, 0.0, -450.0, 0.0, 0.0, 0.0)
@vp = viewport.create()
@msh =mesh.create(8, 12)
mesh.vertex.set(@msh, 0, -50.0, 50.0, -50.0)
mesh.vertex.set(@msh, 1, 50.0, 50.0, -50.0)
mesh.vertex.set(@msh, 2, 50.0, -50.0, -50.0)
mesh.vertex.set(@msh, 3, -50.0, -50.0, -50.0)
mesh.vertex.set(@msh, 4, -50.0, 50.0, 50.0)
mesh.vertex.set(@msh, 5, 50.0, 50.0, 50.0)
mesh.vertex.set(@msh, 6, 50.0, -50.0, 50.0)
mesh.vertex.set(@msh, 7, -50.0, -50.0, 50.0)


mesh.triangle.set(@msh, 0, 0, 1, 2)
mesh.triangle.set(@msh, 1, 0, 2, 3)
mesh.triangle.set(@msh, 2, 1, 5, 6)
mesh.triangle.set(@msh, 3, 1, 6, 2)
mesh.triangle.set(@msh 4, 5, 4, 7)
mesh.triangle.set(@msh, 5, 5, 7, 6)
mesh.triangle.set(@msh, 6, 4, 0, 3)
mesh.triangle.set(@msh, 7, 4, 3, 7)
mesh.triangle.set(@msh, 8, 4, 5, 1)
mesh.triangle.set(@msh, 9, 4, 1, 0)
mesh.triangle.set(@msh,10, 3, 2, 6)
mesh.triangle.set(@msh,11, 3, 6, 7)
mesh.generate(@Msh)

viewport.display(@vp)
sequence.play(@Seq, @Msh)