Low Level API

Realsoft Graphics Oy		Low Level API
	Built-in JavaScript Classes

Scripting languages are linked to Realsoft 3D through a small set of low level functions corresponding to those used in the Realsoft 3D SDK 'C' API.

	Note
	The API described here is not indended for end users but for class implementators and other advanced users who need to get full control over Realsoft 3D.

Scrips can access Realsoft 3D through two variables:

r3MainWindow - root of the user interface (main window)
r3Model - root of the model (functionality).

These variables are actually 'pointers' which point to different type of objects depending on the application.

Functions

All the low level functions deal with Realsoft 3D objects rather than JavaScript objects. For sake of speed, there is no type checking. Passing wrong type of parameter to a function may crash the program. Type checking is only implemented by higher level JavaScript API.

Function:

include - include a JavaScript file

Syntax:

include(filename);

Parameters:

filename - JavaScript file to be included

Returns:

Description:

Loads in given JavaScript file, if not already loaded. This function corresponds to #include directive of 'C/C++' and can be used for loading JavaScript files defining "proto type" objects (in Java or C++, these would be called 'classes').

Example:

include("oops/r3button.js");

Function:

load - load a file

Syntax:

load(filename);

Parameters:

filename - the name of JavaScript file to be loaded

Returns:

Description:

Loads in given JavaScript file. Unlike include(), this function doesn't detect whether the file was already loaded. A file can be loaded any number of times.

Example:

load("myclasses/toolbars/mycreationtools.js");

Function:

MakeID - Create an IFF identifier

Syntax:

id = MakeID(a,b,c,d);

Parameters:

a,b,c,d - four ascii values

Returns:

32 bit IFF identifier

Description:

Creates a 32 bit IFF identifier from the given four 8 bit values.

Example:

var myid = MakeID('I','a','g','e');

Function:

R3New - create a new Realsoft 3D object

Syntax:

obj = new R3New(classid, taglist);

Parameters:

classid - class identifier

Returns:

obj - realsoft 3d object

Description:

Creates a new Realsoft 3D object and returns a handle to it. The type of the object to be created is defined by 'classid'. Properties (attributes) for the object can be defined by one or more tag - value pairs.

Class id, methods and attributes for the object are defined in the object's class header file. All class header files can be found in 'scripts' folder.

Example:

// Create a sphere object
include("real/objects/r3sphere.js");

sphere = R3New(R3CLID_SPHERE,
               [R3RA_Name, "my sphere",
               R3SPHA_Center, new r3Vect(0.0, 0.1, 0.0),
               R3SPHA_Radius, 0.1]);

Function:

R3Dispose - delete object

Syntax:

R3Dispose(obj);

Parameters:

obj - realsoft 3d object to be disposed

Returns:

Description:

Deletes the given Realsoft 3D object

Example:

// create a sphere
sphere = R3New(R3CLID_SPHERE, ...);
...
// delete the sphere
R3Dispose(sphere);

Function:

R3Set - set object attribute

Syntax:

R3Set(obj, id, value, type, flags);

Parameters:

obj - address of Realsoft 3D object

Returns:

Description:

Set attribute. This function corresponds to 'R3SetAttrs()' function of 'C' API. The parameter 'object' refers to Realsoft 3D object. The 'id' is a unique identifier specifying the attribute to be set. The type of the 'value' parameter must match the type of the attribute to be set. There is no run time type conversion and the type of the attribute must be correct or program may crash.

Example:

// move the main window to x=10, y=20
R3Set(r3MainWindow, R3WGA_Left, 10, R3TID_INTEGER, 0);
R3Set(r3MainWindow, R3WGA_Top, 20, R3TID_INTEGER, 0);

Function:: R3Get - fetch object attribute
Syntax:: R3Get(obj, id, value, typeid, flags);
Parameters:: obj - Realsoft 3D object
Returns:: value - fetched attribute.
Description:: Fetch object attribute. This function corresponds to R3GetAttrs() function of 'C' API. Typeid parameter specifies the type of the attribute to be fetched. Supported types are defined in 'oops/r3typids.js'. The 'byvalue' attribute indicates whether the attribute is fetched 'by value' or 'by reference'. This is needed to tell R3Get() whether it should allocate temporary buffer or not.
Example:

    name = R3Get(r3MainWindow, R3WA_Title, R3TID_STRING, R3TNS_COPYSTRING);
    print("Current window title is " + name);

Function:: R3Do - call a method
Syntax:: rc = R3Do(obj, mth, taglist) - call a method
Parameters:: obj - address of Realsoft 3D object
Returns:: rc - method specific return value
Description:: Send a method to Realsoft 3D object. There are six different functions which corresponds to those used by SDK/'C' API. Because JavaScript keeps track of number of passed parameters, there is no need to terminate the tag list by 'R3TAG_END'.
Example:

// Ask the Realsoft 3D to find out its native size
R3DoA(r3MainWindow, R3WGM_FIT, R3WFP_BESTFIT);

Function:: R3ProcessEvents - start event processing
Syntax:: R3ProcessEvents(obj);
Parameters:: obj - main window
Returns:: -
Description:: Start event processing for the given window. There can only be one event loop per application. If there is already an event processing loop running on the application in question, the function returns immediately. Otherwise the function returns when the event loop is terminated.
Example:: R3ProcessEvents(window);

Function:: R3Exit - stop event processing
Syntax:: R3Exit();
Parameters:: -
Returns:: -
Description:: Terminates event processing loop, which most likely causes the program to exit.
Example:

R3Exit();

Function:: R3ClassFind - find class
Syntax:: obj = R3ClassFind(classid);
Parameters:: classid - class identifier
Returns:: obj - class object
Description:: Find class by given id. If the class is not registered, returns NULL.
Example:: In Realsoft Graphics Oy's object oriented programming system, constructor is a class method. Creating a sphere means we call R3RM_CREATE method of the sphere class.

include("real/objects/r3sphere.js");

// find sphere class
class = R3ClassFind(R3CLID_SPHERE);
if(class) {
    // ask sphere class to create sphere instance
    sphere = R3Do(class, R3RM_CREATE,
                  [R3SPHA_Radius, 0.1]);
}

Function:: Class - show class info
Syntax:: Class(name);
Parameters:: name - name of the object
Returns:: -
Description:: Show class specific info.
Example:

Class("CurrentProject.Geometrics.Root");

Function:: Attrs - list public attributes
Syntax:: Attrs(name);
Parameters:: name - hierarchical name specifying the object
Returns:: -
Description:: This function attemps to find the given object and enumerate its attributes. The name is a hierarchical name which identifies an object in the application in question.
Example:

// Ask a sphere to enumerate its attributes 
Attrs("CurrentProject.Geometrics.Root.mylevel.mysphere");

Function:: Get - fetch attribute by name
Syntax:: value = Get(name);
Parameters:: name - hierarchical name specifying a Realsoft 3D attribute to be fetched
Returns:: obj - attribute
Description:: Fetches an attribute by symbolic name.
Example:

// fetch the addres of the project list object in Realsoft 3D
aProjectList = Get("");

// fetch the current project object
aCurrPrj = Get("CurrentProject");

// fetch the name of the current project
sName = Get("CurrentProject.Geometrics.Name");

// fetch the name of the Root level
sName = Get("CurrentProject.Geometrics.Root.Name");

Function:: Set - set public attribute
Syntax:: rc = Set(name, value);
Parameters:: name = symbolic name identifying the object/attribute
Returns:: -
Description:: Set public attribute.
Example:

// rename the root level
Set("CurrentProject.Geometrics.Root.Name", "my new root");

// set the radius and center of 'mysphere'
Set("CurrentProject.Geometrics.Root.mysphere.Radius", 0.2);
Set("CurrentProject.Geometrics.Root.mysphere.Center", new r3Vect(0.2, 0.1, 0));

// set current animation frame 
Set("CurrentProject.Animator.Frame", 30);

Function:: Co - set Current Object
Syntax:: ok = Co(name);
Parameters:: name - symblic name
Returns:: ok - true if succeeded
Description:: Make the given object the current working object. Names passed to Get(), Set() and Attrs() functions are relative to the current object.
Example:

// make the 'root' level the current working object
Co("CurrentProject.Geometrics.Root");

// change the root's name
Set("Name", "my root level");

Function:: Up - make the parent object the current object
Syntax:: Up();
Parameters:: -
Returns:: -
Description:: Make the parent object the current working object. Returns false if there is no parent object.
Example:

// make the 'root' level the current working object
Co("CurrentProject.Geometrics.Root");

// change the root's Translate attribute
Set("Translate", new r3Vect(0, 0, 0));

// pop up one level
Up();

// set root object's name
Set("Root.Name", "my root level");


Coordinate System Class		Matrix Class