3Di API

ActionScript 2 API

With 3Di, Flash objects can now have another dimension. The addition of the third dimension allows users to view objects moving forward or backward towards the viewpoint. As objects move away from the camera, they appear smaller due to perspective projection.

By default, objects are two dimensional and no 3D properties are used or calculated. However, once a 3D property is set (x or y rotation, z translation or scale or 3d matrix) the object becomes three dimensional. At that point, a 3D transformation matrix is automatically created and assigned to the object. The object can be returned to a completely 2D state by setting its 3d matrix to null (i.e. foo._matrix3d = null in ActionScript). Setting only the rotations and z values to 0 will not remove the 3D transformation.

As mentioned above, 3D rotation allows rotation around any of the 3 axes, x, y, or z, as opposed to the 2D case which only rotates around the Z axis. Similarly, 3D scale adds an extra axis for scaling, with the _zscale ActionScript extension.

The default 3D coordinate system and camera in Scaleform is the same as the one found in Flash 10. It is a Right-Handed system, with +X to the right, +Y down and +Z going into the screen (away from the viewer). The default camera is looking down the +Z axis with a FOV angle of 55 degrees.

3D properties can be applied to the following types of Flash objects:

The following ActionScript extensions were added for 3Di:

The use of these new extensions requires the global variable, gfxExtensions, to be set to true in ActionScript.

If you plan on modifying the rotation of a movie clip instance, make sure to note of the location of the registration point. By default, when you create a movie clip symbol, the registration point is set to the top left corner. If you apply a 3D rotation to the movie clip instance using _xrotation or _yrotation, the object will rotate around the registration point. The registration point can be set to the center of the symbol if desired. Make sure to set the registration point carefully if you want to apply rotation to the object using 3Di.

Example 1

Rotate a movieclip 45 degrees around the Y axis:

_global.gfxExtensions = true;
mc1._yrotation = 45;

Example 2

Continuous rotation around X axis along with a Z scale:

_global.gfxExtensions = true;
sq1._zscale = 500;

function rotateAboutXAxis(mc:MovieClip):Void 
{
    mc._xrotation = mc._xrotation + 1;
    if (mc._xrotation > 360) 
    {
        mc._xrotation = 0;
    }   
}

onEnterFrame = function() 
{
    rotateAboutXAxis(sq1);
}

Example 3

3D transformation using a 3D translation matrix applied to the root:

function PixelsToTwips(iPixels):Number
{   
    return iPixels*20;  
}


function TranslationMatrix(tX, tY, tZ):Array 
{
    var matrixC:Array = [   1, 0, 0, 0,  
                            0, 1, 0, 0,  
                            0, 0, 1, 0,  
                            tX,tY,tZ,1];
    return matrixC;
}

this._matrix3d = TranslationMatrix(PixelsToTwips(100),PixelsToTwips(100),0);

3Di from C++

Matrix4x4

A class named Matrix4x4 was added to represent a 4x4, row major matrix. This class has all the appropriate functions for creating and manipulating various types of 3D matrices including general world transformations as well as view and projections. See Render_Matrix4x4.h for details.

Direct Access

The Direct Access interface (via the GFx::Value class) has been expanded to support 3Di. 3D properties can now be set or queried with the new API. These functions are analogous to the 3Di ActionScript extensions.

See the GFx::Value::DisplayInfo class in GFx_Player.h for more details.

voidSetZ(Double z)  
voidSetXRotation(Double degrees)
voidSetYRotation(Double degrees)
voidSetZScale(Double zscale)
voidSetFOV(Double fov)
voidSetProjectionMatrix3D(const Matrix4F *pmat)
voidSetViewMatrix3D(const Matrix3F *pmat)
boolSetMatrix3D(const Render::Matrix3F& mat)

Double  GetZ() const
Double  GetXRotation() const
Double  GetYRotation() const
Double  GetZScale() const   
Double  GetFOV() const  
const Matrix4F* GetProjectionMatrix3D() const
const Matrix3F* GetViewMatrix3D() const
boolGetMatrix3D(Render::Matrix3F* pmat) const

Render::TreeNode

3D matrix calls are added to the Render::TreeNode class interface to set the View and Perspective matrices used for rendering the movie in 3D. Although perspective can be set on an individual display object, it is often convenient to set it at the root of the movie, to affect all objects at once.

GFx_Player.h

void SetProjectionMatrix3D(const Matrix4F& m)
void SetViewMatrix3D(const Matrix3F& m);

Example: Changing the Perspective Field of View using Direct Access API

Ptr<GFx::Movie> pMovie = …;
GFx::Value tmpVal;
bool bOK = pMovie->GetVariable(&tmpVal, "_root.Window");
if (bOK)
{
    GFx::Value::DisplayInfo dinfo;
    bOK = tmpVal.GetDisplayInfo(&dinfo);
    if (bOK)
    {   // set perspectiveFOV to 150 degrees
        Double oldPersp = dinfo.GetFOV();
        dinfo.SetFOV(150);
        tmpVal.SetDisplayInfo(dinfo);
    }
}