All of the primitive shapes demonstrated below, with the exception of the trident, extend the Mesh class. Shapes like the triangle, sea turtle, line segment, and skybox extend the Mesh class directly, while the rest extend the AbstractPrimitive class, which in turn extends the Mesh class.

The init object supplied to the constructors of the primitive classes is passed along to the Mesh constructor. This means that there are a number of init object parameters that are common to all the primitive shapes (excluding the trident because it does not extend the Mesh class, and skyboxes, because they do not pass the init object down to the underlying Mesh class).

The majority of these parameters deal with how materials are applied. Materials are covered in more detail in Chapter 5, Materials.

Most of the init object parameters shown in these tables are also properties that can be set or accessed on the object once it has been instantiated. So

var plane = new Plane({bothsides: true});

could also be written as:

var plane = new Plane();
plane.bothsides = true;

Creating a new instance of a primitive class is very straightforward. Once the appropriate class has been imported from the away3d.primitives package, a new instance of the class can be created and added to the scene directly. This is unlike the triangle face, Sprite3D, and segment objects, which first had to be added to a mesh.

In truth, the process we followed to create a triangle face manually is much the same as the process used by the primitive classes. The big difference is that the primitive classes, which all extend the Mesh class (except for the Trident, Skybox, add SkyBox6 classes), add the triangle faces to themselves instead of adding them to a separate instance of the Mesh class.

The initCone() function is used to create and display an instance of the Cone class.

protected function initCone():void
{
  currentPrimitive = new Cone(
  {
      height: 150
  }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Cone class:

The Cube class creates a standard six-sided cube. By default, the sides are oriented so that they are visible from outside. If you want to place the camera inside the cube and see the sides, you can set the flip init object parameter to true, which will reverse the orientation of the triangle faces that make up the sides of the cube.

The initCube() function is used to create and display an instance of the Cube class.

protected function initCube():void
{
  currentPrimitive = new Cube();
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Cube class:

Most of the primitive classes are designed to have a single material applied to them. The Cube class is a little different. Using the cubeMaterials or faces parameters, which both accept a CubeMaterialsData object, you can specify six individual materials to be applied to each side of the cube separately. The CubeMaterialsData class resides in the away3d.primitives.data package.

The CubeMaterialsData constructor takes a number of init object parameters itself: front, back, left, right, top, and bottom. Each of these parameters accepts a material, which will be applied to the appropriate side of the cube.

  new Cube(
  {
    cubeMaterials: new CubeMaterialsData(
      {
        left: new BitmapFileMaterial("one.jpg"),
        front: new BitmapFileMaterial("two.jpg"),
        right: new BitmapFileMaterial("three.jpg"),
        back: new BitmapFileMaterial("four.jpg"),
        top: new BitmapFileMaterial("five.jpg"),
        bottom: new BitmapFileMaterial("six.jpg")
      }
    )
  }
  );

In addition, by setting the mappingType init object parameter to map6 or CubeMappingType.MAP6, it is possible to display a texture that has been split up into two rows and three columns, with each of the six divisions being applied to one of the sides of the cube.

An example of such a texture is shown in the following figure:

This texture can then be applied to the cube like so.

  new Cube(
  {
    mappingType: CubeMappingType.MAP6,
    material: new BitmapFileMaterial("map6.jpg")
  }
  );

The following image shows the results of both the examples:

The Cylinder class creates either a solid or open-ended cylindrical 3D object.

The initCylinder() function is used to create and display an instance of the Cylinder.

class protected function initCylinder():void
{
  currentPrimitive = new Cylinder(
    {
      height: 150
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Cylinder class:

Away3D has two sphere primitives. The geodesic sphere, being constructed with triangle faces of roughly equal size, is the more uniform of the two. This is unlike the regular sphere primitive, where the triangle faces that make up the sphere are smaller towards the top and bottom.

The following image is of a geodesic sphere primitive:

Compare the geodesic sphere with the following image, which is of a regular sphere primitive. Notice how the triangles that make up the regular sphere are much smaller towards the bottom than they are around the middle.

The geodesic sphere will produce a more rounded shape compared with the standard sphere using the same number of triangle faces.

The initGeodesicSphere() function is used to create and display an instance of the GeodesicSphere class.

protected function initGeodesicSphere():void
{
  currentPrimitive = new GeodesicSphere();
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the GeodesicSphere class:

The grid plane is a grid of rectangles, and it is a handy primitive for judging the position of other 3D objects in the scene. Combined with the trident primitive (which is covered in the following section) to show the scene axes, it is very easy to replicate the look of a simple 3D modeling application. As you can see in the following screenshot, grid planes allow you to instantly see a 3D object's position relative to the origin (or any other point in space), which can be invaluable when debugging.

The grid plane is constructed using segments rather than triangle faces. This allows it to display rectangles rather than triangles, which is how the plane primitive (which is constructed using triangle faces) is shown when it has a wire frame material applied to it.

The initGridPlane() function is used to create and display an instance of the GridPlane class.

protected function initGridPlane():void
{
  currentPrimitive = new GridPlane(
    {
      segments: 4
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the GridPlane class:

The LineSegment class is another example of a primitive that is built using segments rather than triangle faces. It can be used to display a line between two points in space. For convenience, you would probably use the LineSegment class rather than build a mesh and then manually add a segment to it as we did in the section The basic elements of a 3D object.

The initLineSegment() function is used to create and display an instance of the LineSegment class.

protected function initLineSegment():void
{
  currentPrimitive = new LineSegment(
    {
      edge: 500
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the LineSegment class:

The plane is a flat, rectangular shape that is only visible from one side, by default. When it is viewed from behind, the back-face culling process (which is used to improve the performance of an Away3D application by not rendering the back side of a triangle face) will prevent the primitive from being drawn. Setting the bothsides init object parameter to true will override this behavior, and ensure that the plane is visible from behind as well as from the front.

The initPlane() function is used to create and display an instance of the Plane class.

protected function initPlane():void
{
  currentPrimitive = new Plane(
    {
      bothsides: true
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Plane class:

The Triangle class creates a three-sided primitive, and the Plane class creates one with four sides. The RegularPolygon class is a little more flexible, and can be used to create regular shapes with any number of sides (as long as it is more than three).

Just like the Plane class, an instance of the RegularPolygon class will not be visible from the back unless the bothsides init object parameter is set to true.

The initRegularPolygon() function is used to create and display an instance of the RegularPolygon class.

protected function initRegularPolygon():void
{
  currentPrimitive = new RegularPolygon(
    {
      bothsides: true
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the RegularPolygon class:

The RoundedCube class produces a cube that has rounded edges. It uses significantly more triangles than the Cube class, so care should be taken to use the RoundedCube class only in situations where the rounded edges can be seen. A rounded and a regular cube off in the distance will look much the same, but the additional triangles used to construct the rounded cube will still take an additional power to process.

The initRoundedCube() function is used to create and display an instance of the RoundedCube class.

protected function initRoundedCube():void
{
  currentPrimitive = new RoundedCube();
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the RoundedCube class:

The sea turtle can't really be considered a primitive shape, but can be created and used just like any other primitive. The sea turtle features heavily in demos created by Rob Bateman, one of the core Away3D developers, whose personal website is http://www.infiniteturtles.co.uk/blog/ (no doubt there is a correlation between the URL and the inclusion of the sea turtle as a primitive with Away3D).

Unlike the other primitives, which have shapes that lend themselves to being generated programmatically, the SeaTurtle class is an example of a complex 3D model that has been exported into an ActionScript file. Chapter 6, Models and Animations, will cover the model formats supported by Away3D, and how they can be exported into ActionScript classes, in more detail.

The initSeaTurtle() function is used to create and display an instance of the SeaTurtle class.

protected function initSeaTurtle():void
{
  currentPrimitive = new SeaTurtle(
    {
      scale: 0.3
    }
  );
  scene.addChild(currentPrimitive);
}

The SeaTurtle class has no init object parameters.

The Skybox class creates a massive cube whose sides face inwards. The dimensions of the skybox are 800,000 x 800,000 x 800,000 units. This compares with the default dimensions of the Cube class, which are 100 x 100 x 100 units. A skybox is designed to enclose the entire scene, including the camera, and usually has a material applied to it that displays a panoramic view displaying the world beyond the scene.

The following image shows two shots of the skybox from the outside, looking through the back of the cube. Usually the camera and all the other 3D objects in the scene will be enclosed by the skybox, but from the outside you can get a sense of how the six sides of the cube can be used to enclose the scene.

The skybox on the left has had some simple numbered bitmap materials applied to each of its sides. This makes it easy to see how the materials passed into the Skybox constructor map to the final result. The skybox on the right has had some specially formatted skybox textures applied to it. This is how a skybox would look in an actual Away3D application.

The initSkybox() function is used to create and display an instance of the Skybox class.

protected function initSkybox():void
{
  currentPrimitive = new Skybox(
    new BitmapFileMaterial("two.jpg"),
    new BitmapFileMaterial("one.jpg"),
    new BitmapFileMaterial("four.jpg"),
    new BitmapFileMaterial("three.jpg"),
    new BitmapFileMaterial("five.jpg"),
    new BitmapFileMaterial("six.jpg")
  );
  scene.addChild(currentPrimitive);
}

The SkyBox class does not take an init object. Instead, it takes six parameters, each one defining a material to be displayed on each of the six sides of the cube. These parameters are listed in the following table:

The Skybox6 class is used to create a skybox, just like the SkyBox class. The only difference is that it takes one material divided into two rows and three columns (much like the Cube class when the mappingType parameter is set to map6), with each of the six segments then being applied to one of the six sides of the cube.

The following figure is a sample of a texture that can be used with the SkyBox6 class:

The initSkybox6() function is used to create and display an instance of the Skybox6 class.

protected function initSkybox6():void
{
  currentPrimitive = new Skybox6(
    new BitmapFileMaterial("map6.jpg")
  );
  scene.addChild(currentPrimitive);
}

The SkyBox6 class does not take an init object. Instead, it takes a single parameter defining the material to be displayed on the cube.

The Sphere class is the second class that can be used to create a spherical 3D object.

The initSphere() function is used to create and display an instance of the Sphere class.

protected function initSphere():void
{
  currentPrimitive = new Sphere();
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Sphere class:

It has already been noted that the GeodesicSphere class produces a more uniform sphere than the Sphere class. So why would you use the Sphere class? The answer become apparent when you apply a bitmap material to 3D objects created using both classes. The following is a screenshot of a 3D object created by the Sphere class. As you can see, the material is neatly applied across the surface of the sphere.

Compare this with how the same material is applied to a 3D object created with the GeodesicSphere class.

It's clear that while the GeodesicSphere class may produce a higher quality mesh, the UV coordinates are a bit of a mess. On the other hand, the Sphere class will apply a material in a much more consistent and usable fashion.

However, this is only an issue when using bitmap materials. When using simple materials like WireframeMaterial, WireColorMaterial, or ColorMaterial, the GeodesicSphere class may be the better choice.

The Torus class creates a doughnut-shaped 3D object.

The initTorus() function is used to create and display an instance of the Torus class.

protected function initTorus():void
{
  currentPrimitive = new Torus(
    {
      radius: 75,
      tube: 30
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Torus class:

The Triangle class is built from a single triangle face. Like the Plane and RegularPolygon classes, instance of the Triangle class will not be visible from the rear unless the bothsides init object parameter is set to true.

The initTriangle() function is used to create and display an instance of the Triangle class.

protected function initTriangle():void
{
  currentPrimitive = new Triangle(
    {
      bothsides: true
    }
  );
  scene.addChild(currentPrimitive);
}

The following table lists the init object parameters accepted by the Triangle class:

The Trident class creates three-colored arrows that represent the X, Y, and Z axes. If the showLetters parameter is set to true each of these axes will also be labeled. It is very useful for debugging, as it can be used to show the orientation of a 3D object. Chapter 3, Moving Objects, explains how the orientation of a 3D object can affect the results of certain functions.

The initTrident() function is used to create and display an instance of the Trident class.

protected function initTrident():void
{
  currentPrimitive = new Trident(100);
  scene.addChild(currentPrimitive);
}
}

The Trident class constructor does not take an init object. The following two parameters in the table are passed directly to the constructor as regular parameters.