Class Documentation

Name:Rotoplex
Version:1.0
ID:ID_ROTOPLEX
Status:Stable
Category:Effect
Date:April 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1999-2003. All rights reserved.
Short:  This class displays spinning 3D dot based objects in realtime.



Description

The Rotoplex class demonstrates and tests the real-time capabilities and drawing speeds of the graphics system. It features a number of different 3D objects (Cube, Helix, Enneper and Sphere), and has support for the scaling and rotation of each object. The objects are drawn as a cluster of pixels randomly arranged into the shape of the selected 3D object. While the Rotoplex class was created for use in object scripts, it can also be used by standard programs for more flexible options (such as creating your own 3D models for rotation).

This class uses a timer based event to achieve real time rotation, and can be expected to use a reasonable amount of processor time while it is active. The class will not clear the background, so you will be expected to provide a graphical object to use as the background under the Rotoplex object. Here is an example of how a Rotoplex object could be set up:

  <render width="300" height="200"/>
    <box colour="#000000"/>
    <rotoplex maxelements="1000" shape="cube" xspeed="4" yspeed="7"/>
  </render>

It is possible to attach scrollbars to the Rotoplex object so that the user can move its position on the X, Y and Z axis. To set this up, the DScroll, HScroll and VScroll fields can be set to refer to the Scroll object of individual scrollbars. This is demonstrated in the Rotoplex script (scripts:demos/rotoplex.dml).

The speed of rotation can be altered by setting the XSpeed, YSpeed and ZSpeed fields. The 3-Dimensional position of the object can be altered by setting the XCoord, YCoord and ZCoord fields (which are considered to be offsets from the center of each axis). Finally, the current angles of the object can be set or read from the AngleX, AngleY and AngleZ fields.

Structure

The Rotoplex object consists of the following public fields:

AngleX  Defines the angle of rotation on the X axis.
AngleY  Defines the angle of rotation on the Y axis.
AngleZ  Defines the angle of rotation on the Z axis.
DScroll  Reference to a scrollbar for depth based movement.
HScroll  Reference to a scrollbar for horizontal movement.
MaxElements  The total number of dots used to make up the object.
Object  Allows custom objects to be created.
Shape  A pre-calculated object can be selected by writing to this field.
VScroll  Reference to a scrollbar for vertical movement.
XCoord  Defines the horizontal coordinate of the Rotoplex object.
XSpeed  Determines the speed of rotation along the X axis.
YCoord  Defines the vertical coordinate of the Rotoplex object.
YSpeed  Determines the speed of rotation along the Y axis.
ZCoord  Defines the depth-based coordinate of the Rotoplex object.
ZSpeed  Determines the speed of rotation along the Z axis.
Field:AngleX
Short:Defines the angle of rotation on the X axis.
Type:FLOAT
Status:Read/Init

The AngleX field defines the current rotation of the 3D object on the X axis. When the field is set to 0, the object will appear in its default non-rotated state on the X axis.


Field:AngleY
Short:Defines the angle of rotation on the Y axis.
Type:FLOAT
Status:Read/Init

The AngleY field defines the current rotation of the 3D object on the Y axis. When the field is set to 0, the object will appear in its default non-rotated state on the Y axis.


Field:AngleZ
Short:Defines the angle of rotation on the Z axis.
Type:FLOAT
Status:Read/Init

The AngleZ field defines the current rotation of the 3D object on the Z axis. When the field is set to 0, the object will appear in its default non-rotated state on the Z axis.


Field:DScroll
Short:Reference to a scrollbar for depth based movement.
Type:OBJECTID
Status:Read/Write

If you want to attach a positioning scrollbar to the Z coordinate of a Rotoplex object, set this field to an object belonging to the Scroll class. So long as the scroll object is set up to provide full scrollbar functionality, the user will be able to manipulate the position of the Rotoplex object along the Z axis.


Field:HScroll
Short:Reference to a scrollbar for horizontal movement.
Type:OBJECTID
Status:Read/Write

If you want to attach a positioning scrollbar to the X coordinate of a Rotoplex object, set this field to an object belonging to the Scroll class. So long as the Scroll object is set up to provide full scrollbar functionality, the user will be able to manipulate the position of the Rotoplex object along the horizontal axis.


Field:MaxElements
Short:The total number of dots used to make up the object.
Type:LONG
Status:Read/Init

You can set the total amount of dots that the Rotoplex object should use by setting this field. If you do not set this field, the Rotoplex object will set a default value here before creating the 3D pixel array.


Field:Object
Short:Allows custom objects to be created.
Type:struct DotObject *
Status:Read/Init

This field points to an array of 3D dots that specify the makeup of the rotating object. Writing to the field is useful if you wish to create your own 3-Dimensional object rather than use a pre-generated one.

The DotObject structure is defined as follows:

   struct Pixels {
      LONG TotalPixels;
      struct DotPixel *Pixels;
   };

Keep in mind that you will also need to set the TotalDots field so that the Rotoplex class knows how large the array is.


Field:Shape
Short:A pre-calculated object can be selected by writing to this field.
Type:LONG
Status:Read/Init

You can define what 3D object you want the Rotoplex to use by selecting one of the available types as listed here:

RP_ENNEPER
RP_HELIX
RP_SPHERE
RP_CUBE

If the field is not set, an object type will be randomly chosen from the available list on initialisation.


Field:VScroll
Short:Reference to a scrollbar for vertical movement.
Type:OBJECTID
Status:Read/Write

If you want to attach a positioning scrollbar to the Y coordinate of a Rotoplex object, set this field to an object belonging to the Scroll class. So long as the Scroll object is set up to provide full scrollbar functionality, the user will be able to manipulate the position of the Rotoplex object along the vertical axis.


Field:XCoord
Short:Defines the horizontal coordinate of the Rotoplex object.
Type:FLOAT
Status:Read/Write

The horizontal position of the Rotoplex object can be altered by writing to this field. The new position will be reflected on the next drawing cycle, which will typically be within the next 1/25th of a second.


Field:XSpeed
Short:Determines the speed of rotation along the X axis.
Type:FLOAT
Status:Read/Init

You can set the speed of the object's rotation along the X axis by writing to this field. The acceptable range for the value is between -1000 and +1000, but typically you will get the best results by using values between -5 and +5.


Field:YCoord
Short:Defines the vertical coordinate of the Rotoplex object.
Type:FLOAT
Status:Read/Write

The vertical position of the Rotoplex object can be altered by writing to this field. The new position will be reflected on the next drawing cycle, which will typically be within the next 1/25th of a second.


Field:YSpeed
Short:Determines the speed of rotation along the Y axis.
Type:FLOAT
Status:Read/Init

You can set the speed of the object's rotation along the Y axis by writing to this field. The acceptable range for the value is between -1000 and +1000, but typically you will get the best results by using values between -5 and +5.


Field:ZCoord
Short:Defines the depth-based coordinate of the Rotoplex object.
Type:FLOAT
Status:Read/Write

The Z coordinate of the Rotoplex object can be altered by writing to this field. The range is limited between -100 and +100. 0 is considered to be the center of the Z plane, while -100 is the furthest possible point away from the field of view. A value of +100 is the closest possible point to the beginning of the field of view.


Field:ZSpeed
Short:Determines the speed of rotation along the Z axis.
Type:FLOAT
Status:Read/Init

You can set the speed of the object's rotation along the Z axis by writing to this field. The acceptable range for the value is between -1000 and +1000, but typically you will get the best results by using values between -5 and +5.