Using Sandy 3.0 Flash Library

By Petit

Content

Part 1, Introduction
Part 2, Jump Start
Part 3, The Sandy Primitives, Planes, Hedra, Sphere, Line, Cylinder, Torus
Part 4, Transformations
Part 5, Materials, Bitmaps, Movie clips and video
Part x, Physics using jiglibflash

Part 1. Introduction

This tutorial is using the Sandy 3.0.2 version.
To compile the examples using version 3.1 or 3.1.1, see Version upgrade
These tutorials will be updated and expanded in due time ( due, mark you :)

Sandy 3D Flash library or 3D Engine comes in different flavors and is in constant development. At the time of writing ( September 2007 ), there is a stable 1.1 version and a fairly stable 1.2 version for AS2. There is also a 2.0 version for AS2 under development. Sandy 3.0.x, which is the one I am going to cover here, is the first AS3 version. To develop AS3 applications you'll need Flash CS3, the Flex SDK command line compiler or the free FlashDevelop. To run them you need Flash Player 9. You also need Sandy 3.0.1 version or greater.

This is the start of a series of tutorials like Using Sandy 3D Flash Library, for Sandy 1.1 and AS2. Make sure you visit the Sandy wiki and the Sandy user forum. If you are the daring kind, get the latest developer version from the SVN. I'll be using the trunk version. In the wiki, browse through the FAQ section, to to learn a bit more about Sandy. And you will have an invaluable help of the API documentation.

If you know Sandy before, and just want a quick introduction to the 3.0 version, take a look at the Jump Start page.

Max Pellizzaro has written some beginner and advanced tutorials for the Sandy wiki.

Some Views on the Sandy world

We can describe a Sandy world in different ways, depending on what properties we are interested in. The different representations, or conceptual views, adds to the understanding of how it is built.

What the visitor sees, is a 2D presentation on screen, drawn with perspective and shadows to fool him/her to interpret the image as 3 dimensional. The goal of a 3D library is to make this illusion as good as possible.

The concept closest to the real world, is that of a limited 3D space with 3D objects at different positions, and with a camera ( the eye of the viewer ) looking at the scene from a certain position. The objects, as well as the camera, can be moved around in the world, creating an animated projection on the film or the retina of the eye.

Behind this lies a mathematical 3D model and a transformation from 3D to 2D, normally using vector an matrix calculations. Vectors and matrices are also used to move things around, by a combination of translations and rotations. This is the mathematical view.

The internal structure of the Sandy world, as in any other computer generated 3D worlds is described as an object tree graph, with nodes and branches. This important view deserves its own chapter and is described below.

Another view is the object oriented class hierarchy. All nodes in the tree graph are represented by classes that extend the Node class. The Group class extends the Node class directly, while the TransformGroup and Shape3D gets their mobility by extending the ATransformable class.

The Sandy Scene Graph

( This is mainly a repetition of the description in the 1.1 tutorial )

To understand the structure of a 3D world, we normally use the concept of a scene graph or a tree. The scene graph describes the relationship between the different parts making up the world. Traditionally the world itself is represented by a "World" or "Universe" object. The tree is comprised of node's, branches and leaves, rooted in the world object's Root Node, or Locale.

Branches extend from the single root node, and contain other nodes with different properties and responsibilities. There are three types of nodes in Sandy, the Group, the TransformGroup and the Shape3D.

The Group and TransformGroup are branch nodes, which means they can have children in a sub tree or branch. A Group is a general grouping node, while a TransformGroup is used to apply transformations, such as rotations and translations to all its children.

An Shape3D represents a visible 3D object in the world. It is a Leaf node, i.e. it cannot have any child nodes. In version 3.0 the Shape3D, as well as the TransformGroup extends ATransformable, facilitating all kinds of movements. It is no longer necessary to create transform groups or other explicit transform objects, to move 3D objects around.

If we look at the simple scene graph above, on the left we have a branch with a TransformGroup and another branch group. It ends in a Leaf node, the Shape3D, with two associated property objects called Geometry and Appearance. The Geometry contains the data necessary to build the geometrical shape of the object, and the Appearance contains data for the looks of the object, such as textures and colors.

The groups we see on the right side represents the users view of the world and the physical environment, such as screen and user input widgets. Interaction with the user is handled by an event handling system, and most of the objects can register event subscriptions and broadcast events.

In the Sandy 3.0 view platform, the Camera 3D object can be added to any group node in the tree graph, allowing for complex movement of the camera. The View Object itself doesn't exist as a concrete object, so don't search for it ;). The View represents the data necessary to calculate the users 2D view of the world. It contains the Camera3D and and is associated with a screen object, on which all visible objects are rendered.

Coding the world