AlUniverse

Synopsis

#include <AlUniverse.h>

class AlUniverse : public AlMessage

enum AlFileType {

	kUnknown,	// File type is unknown and will be ignored by ::retrieve().

	kWire,	// Autodesk Wire File

	kIges,	// Initial Graphics Exchange Standard

	kVdais,	// Verband Der Automobilindustrie IGES Subset

	kC4x,	// EDS/GM format.

	kJamais,	// Japan Automobile Manufacturers Association IGES Subset.

	kVdafs,	// Verband Der Automobilindustrie Freeform Surface Interface.

	kDxf,	// Drawing Exchange Format

	// The file types below are available only in OpenAlias.

	kDes,	// EDS/GM Data Exchange Standard

	kTri,	// Autodesk Object Separated Triangle Format

	kQuad,	// Autodesk Object Separated Quad Format

	kProRender,	// Pro/Engineer Render File Format.

	kInventor,	// OpenInventor Metafile Subset V1.0

	kStl,	// 3D Systems SLA Format

	kObj,	// Autodesk TAV format.

	kEpsf,	// Adobe Encapsulated Postscript v2.x

	kIllustrator,	// Illustrator Format.

	kSlc	// 3D Systems Slice Format.

};

// Project subdirectory types.

// These indicate the subdirectories where different types of files are

// located.

enum AlDirectoryType {

kAnimData,	// Animation data (Save Anim / Retrieve Anim)

kCanvasData,	// Paint canvas files

kDepthData,	// Depth files

kEnvironmentData,	// Environment files (saved/retrieved via

							// multi-lister)

kLightData,			// Light files (saved/retrieved via multi-lister)

kMaskData,			// Mask files

kMiscData,			// Miscellaneous data files: color, window and so on.

kOptionData,		// UI option files

kPixData,			// Image files for file textures, image planes and so on.

kPlotData,			// Plot files

kRibData,			// Pixar RIB files

kSlaData,			// Stereo Lithography files (.stl, .slc, .tri)

kSdlData,			// Scene Description Files

kShaderData,		// Shader files (saved/retrieved via multi-lister)

kStageData,			// Wire files representing stages.

kTextureData,		// Texture files (saved/retrieved via multi-lister)

kWireData			// Wire files an CAD files (for example, IGES, DXF, and so on.)

};

enum AlApplicationMode

kOpenModel,

kOpenAlias

};

enum AlLayerSortMode{

kLayerNumber,

kLayerName

};

static statusCode			initialize( AlCoordinateSystem = kZUp,

boolean initProjectEnv = FALSE  );

static boolean	isInitialized();

static AlCoordinateSystem	coordinateSystem ();

static statusCode	expandFileName( char[], const char *,

AlDirectoryType directoryType );

static boolean	isWireFile( const char *, char * );

static boolean AlUniverse::isOldWireFile( const char *fileName );

static statusCode	wireFileWindowSize( int &sizeX, int &sizeY );

static statusCode	setWireFileWindowSize( int sizeX, int sizeY );

static AlFileType	fileType( const char * );

static statusCode	retrieveOptions( AlRetrieveOptions& );

static statusCode	setRetrieveOptions( const AlRetrieveOptions& );

static statusCode	retrieve( const char * );

static statusCode	retrieve( const char *, void(*)(int) );

static const char*	lastWireFileRetrieved();

static const char*	lastFileSaved();

static statusCode	store( const char *, AlDagNode* = NULL );

static statusCode	storeActive( const char * );

static AlDagNode*	firstDagNode();

static AlSet*	firstSet();

static AlCluster*	firstCluster();

static const char*	currentStage( void );

static statusCode	setCurrentStage( const char* );

static statusCode	mergeStage( const char* );

static statusCode	mergeAllStages( void );

static statusCode	deleteStage( const char* );

static statusCode	deleteAllStages( void );

static statusCode	stageVisibility( const char *, boolean& );

static statusCode	setStageVisibility( const char *, boolean );

static const char*	stageWindowSource( void );

static statusCode	setStageWindowSource( const char * );

static const char*	stageBackgroundSource( void );

static statusCode	setStageBackgroundSource( const char * );

static statusCode	renameStage( const char *, const char * );

static AlList*	stageNames( void );

static statusCode	createNewStage( const char *, char*& );

static statusCode	retrieveStageSet( const char *,boolean );

static statusCode	saveStageSet( const char *);

static statusCode	setStageWireFileName( const char *, const char * );

static const char*	stageWireFileName( const char * );

static AlWindow*	firstWindow();

static AlWindow*	currentWindow();

static AlWindow*	sbdWindow();

static AlImagePlane*	firstImagePlane();

static statusCode	blindData( int, long&, const char*& );

static statusCode	blindData( int, int, long&, const char*& );

static statusCode	setBlindData( int, long, const char* );

static statusCode	removeBlindData( int );

static statusCode	removeBlindData( int, int );

static AlChannel*	firstChannel();

static AlChannel*	nextChannel(AlChannel *);

static statusCode	nextChannelD( AlChannel *);

static AlAction*	firstAction();

static AlAction*	nextAction(AlAction *);

static AlShader*	firstShader();

static AlShader*	nextShader( AlShader* );

static statusCode	nextShaderD( AlShader* );

static AlEnvironment*	firstEnvironment();

static AlLayer*	firstLayer();

static AlLayer*	nextLayer( AlLayer* );

static statusCode	nextLayerD( AlLayer* );

static AlLayer*	layerByNumber(int);

static AlLayer*	creationLayer();

static statusCode	setCreationLayer(AlLayer *);

static boolean	layersEnabled();

static statusCode	setLayersEnabled( boolean );

static statusCode	sortLayersInLayersBar(AlLayerSortMode);

static AlPerspectiveCamera*	firstCamera();

static AlPerspectiveCamera*	nextCamera( AlPerspectiveCamera* );

static statusCode	nextCameraD( AlPerspectiveCamera* );

static AlLocator*	firstLocator();

static AlLocator*	nextLocator(AlLocator *);

static statusCode	deleteAll();

static statusCode	deleteAllLocators();

static AlConstructionEntity*	firstConstructionEntity();

static AlConstructionEntity*	nextConstructionEntity(AlConstructionEntity *);

static statusCode	nextConstructionEntityD(AlConstructionEntity *);

static statusCode       	deleteAllConstructionEntities();

static statusCode	importCloudFile( const char *, int );

static AlCloud	*firstCloud();

static int	numberOfClouds();

static AlBlendCurve*	firstBlendCurve();

static int	numberOfBlendCurves();

static statusCode	redrawScreen( unsigned int flags = kRedrawInactive | kRedrawActive );

static statusCode	applyIteratorToImagePlanes( AlIterator*, int& );

static statusCode	applyIteratorToWindows( AlIterator *, int& );

static statusCode	applyIteratorToDagNodes( AlIterator *, int& );

static statusCode	applyIteratorToActions( AlIterator *, int& );

static statusCode	applyIteratorToChannels( AlIterator *, int& );

static statusCode	applyIteratorToSets( AlIterator *, int& );

static statusCode	applyIteratorToClusters( AlIterator *, int& );

static statusCode	applyIteratorToShaders( AlIterator *, int& );

static statusCode	applyIteratorToLocators(AlIterator *, int &);

static statusCode	applyIteratorToLayers(AlIterator *, int &);

static statusCode	applyIteratorToClouds(AlIterator *, int &);

static statusCode	applyIteratorToBlendCurves(AlIterator *, int &);

static statusCode	writeSDLNoAnimation( const char *, boolean );

static statusCode	writeSDL( const char *, boolean, double, double, double );

static statusCode	frameRange(AlFrameRangeType, double&, double&, double&);

static double	currentTime();

static statusCode	doUpdates( boolean = TRUE );

static boolean	updatesOn()

static AlApplicationMode	applicationMode();

static statusCode	userPrefColor( int, int&, int&, int& );

static statusCode	setUserPrefColor( int, int, int, int );

static boolean	constructionPlaneInEffect();

static statusCode	constructionPlaneTransform( AlTM& );

static AlCategory	*firstCategory();

static AlCategory	*nextCategory(AlCategory *);

Description

This is a static class in that all of its member functions are static. It provides the foundation on which to interface with Alias Wire Files (OpenModel) or with Alias directly (via OpenAlias).

In Alias, there is the concept of a ’stage’, an independent entity that encapsulates all the top-level information about a modeling environment. The stage effectively represents the running version of an individual Wire file. In the interactive package, stages can be controlled through the Stage Editor. The identical control also exists in the AlUniverse class, via the Stage functions. These let you switch between stages, create and destroy stages, merge stages, and alter their features.

OpenAlias and OpenModel use object data that defines, among other things, transformations, curve and surface geometry, cameras, and lights. Transformations are kept in objects called "DAG nodes". DAG nodes can be connected to other DAG nodes to form a list of DAG nodes. There are particular types of DAG nodes which refer specifically to geometry, cameras, lights, or refer to another list of DAG nodes to form a hierarchical structure. Together, these different types of DAG nodes can be used to build a list of hierarchical structures which is collectively called a directed acyclic graph or "DAG".

The AlUniverse class gives access to the first DAG node in the DAG, and from that DAG node, the list of all DAG nodes in the universe can be traversed.

The object data may also contain animation information on various animatable items, such as a DAG node or a piece of geometry. The animation information can be accessed through the item that is animated. The AlUniverse class also gives access to animation data through global lists.

Geometry also contains shading information. Each surface or face (a particular kind of curve) contains a list of shaders. The AlUniverse class also gives access to a global list of all shaders in the universe, as well as the single environment class.

The AlUniverse class also gives access to the list of sets in the universe via the firstSet() method. Similarly, the firstCluster() method gives access to all the clusters in the universe. However, clusters are also accessible through methods in the classes that can belong to clusters (that is, AlDagNode, AlCurveCV and AlSurfaceCV). A cluster is an object in the DAG that has a collection of DAG nodes and/or CVs. The transformations in the DAG nodes above the cluster are applied to the CVs in the cluster after the latter’s own transformations have been applied.

AlUniverse provides base access to the ImagePlane list and the Window list through firstImagePlane(), firstWindow() and related functions.

Whenever a new Alias object of any kind is created, it is added to the appropriate place in the universe. For example, if a DAG node is created, it is traversable through the AlUniverse::firstDagNode() method. If a new animation action is created, it is accessible by walking the list of actions via AlUniverse::firstAction()/nextAction().

However, there are a few exceptions. The AlCurve, AlFace, AlSurface and AlKeyframe classes can all be created and will not be part of the universe initially. They will become part of the universe when they are added to other objects. For example, an AlCurve becomes part of the universe when its AlCurveNode is created. An AlKeyframe becomes part of the universe when its AlParamAction is created. If a class is not part of the universe, this means that if AlUniverse::store() is called, that class will not be stored. If an OpenAlias plug-in exits without making an object part of the universe, then the data will be lost and wasted memory will result.

The initialize method must be called before any other AlUniverse method is called. A Alias AlObject cannot be created until the initialize method is called.

statusCode AlUniverse::doUpdates( boolean newState )

Description

Notifies the system that you are finished performing. If this flag is TRUE, then it is equivalent to sending out a ’geometry modified’ message to the rest of the system. When the system receives the update message, then operations such as construction history, and so on are done. If the previous state of the flag was FALSE and the new state is TRUE, then an update will be done now and on each subsequent DAG modification.

boolean AlUniverse::isInitialized()

Description

Returns TRUE if the initialize method has been called.

statusCode AlUniverse::initialize( AlCoordinateSystem up, boolean initProjectEnv )

Description

Initializes the OpenAlias/OpenModel environment so that Alias object data can be retrieved, created, and/or stored. The world space coordinate system of the Universe can be oriented so that either the positive Y-axis or positive Z-axis is considered the "up" direction. This method will do nothing if called more than once. By default OpenModel applications are not aware of the Alias project environment (for example, user_data/demo/wire etc). By passing TRUE as the second argument, the OpenModel application will become aware of the Alias project environment, expect such an environment to exist, and will use it for locating files. The .Alias* setup files will be read and processed. However, unlike Alias, when the OpenModel application starts, if the project environment does not exist, it will not be created, and the application will proceed in the default manner. Note that the arguments have no effect when initialization occurs under OpenAlias. That is, the world space coordinate system and the project environment are determined by the running Alias application.

Arguments

< up - indicates whether the y-axis (kYUp) or z-axis (kZUp) should be the up direction. If no argument is specified, the default is kZUp. This parameter has no effect when using OpenAlias.

< initProjectEnv - indicates whether the OpenModel application is to be aware of the Alias project environment or not. The default if FALSE.

Return Codes

sSuccess - universe initialized

sAlreadyCreated - the universe is already initialized

sInsufficientMemory - not enough memory to initialize

sFailure - could not initialize

sNoProjectEnvironment - this will be the case if initProjEnv is TRUE and Alias project environment does not exist.

boolean AlUniverse::isOldWireFile( const char *fileName )

Description

Determine if a file is an old Alias wire file.

Return values

TRUE - the indicated file is a valid Wire file

FALSE - one of the arguments was invalid or the file was not a Wire file.

AlCoordinateSystem AlUniverse::coordinateSystem()

Description

Returns the current world space coordinate system of the Universe. Note that once AlUniverse::initialize has been called, or while running under OpenAlias, the coordinate system will never change during "this" session.

Return values

kYUp - positive Y-axis is "up"

kZUp - positive Z-axis is "up"

statusCode AlUniverse::expandFileName( char expandedName[], const char *fileName, AlDirectoryType directoryType )

Description

Given a filename, expands to an absolute pathname based on the file’s type and Alias project environment.

Arguments

> expandedName - location to return expanded filename.

< fileName - name of the file to locate within the project environment. Must not contain leading slashes or dots.

< directoryType - the type of project subdirectory where the file is located. (See AlUniverse.h for possible values.

Return Codes

sSuccess - the fully expanded name was successfully constructed and the file exists

sInvalidArguments - the passed filename is already absolute (contains leading ’/’), or is relative (contains

leading ’..’), or the directory type is invalid

sNoProjectEnvironment - the returned path does not exist. This may be because the Alias project environment does not exist in whole or in part.

SFailure - either or both passed names were NULL

statusCode AlUniverse::wireFileWindowSize( int &sizeX, int &sizeY )

Description

Gets the window size that was retrieved on the previous call to AlUniverse::retrieve. This method is available only under OpenModel and fails under OpenAlias.

Return Codes

sSuccess - the store size was set

sFailure - OpenAlias is in use

sInvalidArgument - sizeX <=0 or sizeY <=0

statusCode AlUniverse::setWireFileWindowSize( int sizeX, int sizeY )

Description

Sets the window size that is written to the next call of AlUniverse::store.

Note that these values are changed whenever a call to AlUniverse::retrieve is called.

This method is available only under OpenModel and fails under OpenAlias.

Return Codes

sSuccess - the store size was set

sFailure - OpenAlias is in use

sInvalidArgument - sizeX <=0 or sizeY <=0

boolean AlUniverse::isWireFile( const char *fileName, char * vbuf )

Description

Determines if a file is an Alias wire file and finds the version number.

Note: vbuf must be allocated and at least 8 characters.

Arguments

< filename - the name of the file to check

> vbuf - if the file is an Alias wire file then this buffer will contain the version string

Return values

TRUE - the indicated file is a valid Wire file

FALSE - one of the arguments was invalid or the file was not a Wire file

AlUniverse::AlFileType AlUniverse::fileType( const char *fileName )

Description

Determine a file’s type.

Arguments

< fileName - the name of the file to type check

Return values

kUnknown - file type is unknown and will be ignored by ::retrieve().

The file types listed below are available for import in both OpenModel and OpenAlias.

kWire	Autodesk Wire File
kIges	Initial Graphics Exchange Standard
kVdais	Verband Der Automobilindustrie IGES Subset
kC4x	EDS/GM format
kJamais	Japan Automobile Manufacturers Association IGES Subset
kVdafs	Verband Der Automobilindustrie Freeform Surface Interface
kDxf	Drawing Exchange Format
kStl	3D Systems SLA Format

The file types listed below are available for import only in OpenAlias.

kDes	EDS/GM Data Exchange Standard
kTri	Autodesk Object Separated Triangle Format
kQuad	Autodesk Object Separated Quad Format
kProRender	Pro/Engineer Render File Format
kInventor	OpenInventor Metafile Subset V1.0
kObj	Autodesk TAV format
kEpsf	Adobe Encapsulated Postscript
kIllustrator :	Illustrator Format
kSlc	3D Systems Slice Format

statusCode AlUniverse::retrieveOptions( AlRetrieveOptions &options )

Description

Gets the options used by AlUniverse::retrieve().

Arguments

> options - options that ::retrieve() will use when retrieving files

Return Codes

sSuccess - the options were returned successfully

sInvalidArgument - ’options’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::setRetrieveOptions( const AlRetrieveOptions &options )

Description

Sets the options used by AlUniverse::retrieve().

Arguments

< options - options that AlUniverse::retrieve() will use when retrieving files

Return Codes

sSuccess - the options were set correctly

sInvalidArgument - ’options’ was NULL, or a parameter in ’options’ was out of range

sFailure - AlUniverse was not initialized

statusCode AlUniverse::retrieve( const char *fileName )

Description

Retrieves an Alias Wire file and adds the objects stored in the file to the list of Alias AlDagNode objects. If fileName is NULL the file is read from stdin.

Note that if sInvalidWireFile is returned you are likely trying to retrieve a newer wire file than your application recognizes. In this case you should link your application with the OpenModel library distributed with the newer Alias.

Arguments

< fileName - the name of the file to be retrieved

Return Codes

sSuccess - the file was retrieved successfully

sInsufficientMemory - not enough memory

sFailure - the wire file could not be retrieved properly

sInvalidWireFile - the file was not a compatible Alias wire file

statusCode AlUniverse::retrieve( const char *fileName,void(*progressCallback)(int) )

Description

This method is a variation of the AlUniverse::retrieve(const char *) method with the addition that it allows a retrieve progress callbackto be set.

NOTES:

1. The function progressCallback() should be in the C name space within an extern "C" block.

2. The ’int’ number passed to the progress callback is expressed as a percentage value between 0 and 100. This number is a close approximation of the retrieval progress and will not be exact due to compression usedin the Alias wire file format.

Arguments:

< fileName - the name of the file to be retrieved

Return Codes:

sSuccess - the file was retrieved successfully

sInsufficientMemory - not enough memory

sFailure - the wire file could not be retrieved properly

sInvalidWireFile - the file was not a compatible Alias wire file.

sInvalidArgument - NULL parameter passed to method

const char* AlUniverse::lastWireFileRetrieved()

Description

Returns the last wire file retrieved either by the API or by Alias. Note that the file name will not change to NULL if a delete all is done. NULL is returned if no files have been retrieved or if the function fails.

const char* AlUniverse::lastFileSaved()

Description

Returns the name of the last file saved within Alias. If no file has been saved or the function failed, NULL will be returned. Also note that if the DT options are changed, this function will return NULL until after the next save.

Note: this method will fail and always return NULL in OpenModel.

statusCode AlUniverse::store( const char * fileName, AlDagNode* dagNode )

Description

If the AlDagNode argument is absent or NULL then this method stores all the AlObjects in the universe to a file as an Alias Wire file. If the AlDagNode argument is not NULL then only the model below the AlDagNode is stored. If the AlDagNode is in the middle of a hierarchy, the AlDagNodes above the argument will also be stored so as to preserve transformations on the model.

Arguments

fileName - the name of the file to be stored

dagNode - see description

Return Codes

sSuccess - the file was stored successfully

sFailure - the wire file could not be stored properly

statusCode AlUniverse::storeActive( const char * fileName )

Description

Allows the user to store only those objects which are on the pick list.

Arguments

fileName - the name of the file to be stored

Return Codes

sSuccess - the file was stored successfully

sFailure - the wire file could not be stored properly

AlDagNode* AlUniverse::firstDagNode()

Description

Returns the first AlDagNode in the list of Alias AlDagNode objects (the DAG). NULL is returned if the list is empty.

AlSet* AlUniverse::firstSet()

Description

Returns a pointer to the first set in this universe. Returns NULL if there are no sets in this universe.

AlCluster* AlUniverse::firstCluster()

Description

Returns a pointer to the first cluster in this universe. Returns NULL if there are no clusters in this universe.

AlChannel* AlUniverse::firstChannel()

Description

Returns the first channel in the list of all channels in the universe. This list is not in any particular order, although channels animating the same item will appear consecutively in the list. This method returns NULL if nothing in the universe is animated.

const char* AlUniverse::currentStage( void )

Description

Returns the name of the current stage.

statusCode AlUniverse::setCurrentStage( const char* name )

Description

Switches the current stage to the stage with the indicated name.

Arguments

name - the name of the stage to switch to

Return Codes

sSuccess - the stage was set to the indicated stage

sFailure - the stage with the given name could not be found

statusCode AlUniverse::mergeStage( const char *name )

Description

Merges the current stage with another stage.

Arguments

name - the name of the stage to merge with

Return Codes

sSuccess - the stage was successfully merged

sFailure - a stage with the given name could not be found or the merge operation failed

statusCode AlUniverse::mergeAllStages( void )

Description

Merges all of the stages into a single stage. The current stage is switched to the merged stage.

Return Codes

sSuccess - all of the stages were successfully merged

sFailure - the merge operation failed or there were no stages to merge

statusCode AlUniverse::deleteStage( const char *name )

Description

Deletes the stage with the given name. Under OpenAlias, this operation will not delete the last stage if there is only one stage remaining.

Arguments

name - the name of the stage to delete

Return Codes

sSuccess - the stage was successfully deleted

sFailure - there was no stage with the given name or the delete operation failed

statusCode AlUniverse::deleteAllStages( void )

Description

Deletes all stages. This operation will fail if there is only one stage remaining.

Return Codes

sSuccess - all of the stages were successfully deleted

sFailure - the delete operation failed

statusCode AlUniverse::stageVisibility( const char *name, boolean& on_or_off )

Description

Returns the visibility status of the indicated stage.

Arguments

< name - the name of the stage to examine

> on_or_off - the variable to return the status in

Return Codes

sSuccess - the stage was found and its visibility status was returned

sFailure - there was no stage with the given name

statusCode AlUniverse::setStageVisibility( const char *name, boolean on_or_off )

Description

Sets the visibility status of the indicated stage.

Arguments

name - the name of the stage to alter

on_or_off - TRUE if the stage is visible

Return Codes

sSuccess - the stage was found and its visibility status was set

sFailure - there was no stage with the given name

const char *AlUniverse::stageWindowSource( void )

Description

Returns the name of the currently active application window universe.

statusCode AlUniverse::setStageWindowSource( const char *name )

Description

Sets the window universe to the indicated stage. The window universe contains the windows you are looking through to see the objects in the current universe.

Arguments

name - the name of the stage to set the window universe to

Return Codes

sSuccess - the stage was found and the window universe was set

sFailure - there was no stage with the given name

const char *AlUniverse::stageBackgroundSource( void )

Description

Returns the name of the current background source.

statusCode AlUniverse::setStageBackgroundSource( const char *name )

Description

Chooses which stage to take the background source from (the environment shader) that is used for rendering.

Arguments

name - the name of the stage to use

Return Codes

sSuccess - the stage was found

sFailure - there was no stage with the given name

statusCode AlUniverse::renameStage( const char* oldName, const char *newName )

Description

Renames the stage with the name ’oldName’ to ’newName’. If NULL is specified for oldName, then the current stage is renamed.

Arguments

oldName - the name of the stage to rename

newName - the new name for the stage

Return Codes

sSuccess - the stage was renamed

sNameChangedToUniqueOne - the stage was renamed, but the newName was altered to be unique

sInvalidArgument - the newName was NULL

sFailure - the indicated stage could not be found

AlList* AlUniverse::stageNames( void )

Description

Returns an AlList (of AlNameItems) containing the names of all of the stages that are present.

statusCode AlUniverse::createNewStage( const char* name, char*& stagename )

Description

Creates a new stage and sets the current stage to the new stage. The name assigned to the stage is returned in stagename. Access to stagename is important when stage names are reused and a new unique name is selected. Note that stagename will be assigned to something that can change through calls in the API. So caution must be taken when using stagename in future calls.

In addition, what stagename points to must not be modified since it is internal Alias data.

Arguments

< name - the name of the stage to create

> stagename - pointer to created name

Return Codes

sSuccess - a new stage with the name ’name’ was created

sNameChangedToUniqueOne - a new stage was created, although the newName was altered to be unique

sFailure - a new stage could not be created

statusCode AlUniverse::retrieveStageSet( const char *stageSet, boolean deleteStages )

Description

Retrieves a stage set file.

Arguments

> stageSet - the name of the stage set file to be retrieved

> deleteStages - if true, any existing stages will be deleted

Return Codes

sSuccess - the method succeeded in retrieving the stage set

sFailure - the method failed

sInvalidArgument - stageSet is NULL

statusCode AlUniverse::saveStageSet( const char *stageSet )

Description

Saves a stage set file. This method saves out all of the stages and their associated wire file names.

If a stage has an associated wire file name that is NULL, this routines fails.

Arguments

> stageSet - the name (with path) of the stage set file to be created

Return Codes

sSuccess - the method succeeded in saving the stage set

sFailure - the method failed

sInvalidArgument - stageSet is NULL

statusCode AlUniverse::setStageWireFileName( const char *stageName, const char *wireFileName )

Description

Sets the wire file name that is to be used for the stage when the stage set is written out using the saveStageSet() call.

Note that this function will change the default name of the wire file in the store and retrieve dialog boxes in Alias.

Arguments

> stageName - the name of the stage

> wireFileName - the name of the wire file

Return Codes

sSuccess - the method succeeded in setting the wire file for the stage

sFailure - not a valid stage name or the setting of the wire file name failed

sInvalidArgument - stageSet or wireFileName are NULL

const char* AlUniverse::stageWireFileName( const char *stageName )

Description

Returns the wire file name of stage 'stageName'. NULL is returned if the wire file is not set or if an error occurred.

Arguments

> stageName - the name of the stage

AlWindow *AlUniverse::firstWindow( void )

Description

Returns the first window layer.

statusCode AlUniverse::applyIteratorToWindows( AlIterator *iter, int& rc )

Description

Applies an iterator to each window.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each window

sInvalidArgument - ’iter’ was NULL

AlImagePlane* AlUniverse::firstImagePlane( void )

Description

Returns the first image plane.

statusCode AlUniverse::applyIteratorToImagePlanes( AlIterator* iter, int& rc )

Description

Applies an iterator to each image plane.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each image plane

sInvalidArgument - ’iter’ was NULL

AlWindow* AlUniverse::currentWindow( void )

Description

Returns the currently active window.

AlWindow* AlUniverse::sbdWindow( void )

Description

Returns the current SBD window.

statusCode AlUniverse::blindData( int type, long& size, const char*& ptr )

Description

Retrieves the blind data for the universe. If there is no data, the size will be 0 and the pointer will be NULL.

Arguments

< type - the blind data type to find

> size - the size of the blind data if found

> ptr - a pointer to the blind data if found

Return Codes

sSuccess - the blind data type was found

sFailure - the blind data type was not found

statusCode AlUniverse::blindData( int type, int index, long& size, const char*& ptr )

Description

Retrieves the blind data for the universe. If there is no data, the size will be 0 and the pointer will be NULL

NOTE: If universes are merged then the resulting universe will have blind data for both universes. If there are two or more blind data packets with the same "type", the parameter 'index' can be used to access them.

Arguments

< type - the blind data type to find

< index - the index of the blind data packet

> size - the size of the blind data if found

> ptr - a pointer to the blind data if found

Return Codes

sSuccess - the blind data type was found

sFailure - the blind data type was not found

sInvalidArgument - index was negative

statusCode AlUniverse::setBlindData( int type, long size, const char* ptr )

Description

Associates a block of data with the object. If a block of data is already associated with this object and this user_type, the old block is replaced by a reference to the new block. The old block of data is not deleted.

Arguments

type - the type of the blind data to set

size - the size of the blind data

ptr - a pointer to the blind data

Return Codes

sSuccess - the blind data was set

statusCode AlUniverse::removeBlindData( int type )

Description

Removes the blind data from the universe with the indicated type. Note that the user is still responsible for the memory associated with this block of data.

Arguments

type - the blind data type to remove

Return Codes

sSuccess - the type was found and removed

sFailure - the indicated type could not be found

statusCode AlUniverse::removeBlindData( int type, int index )

Description

Removes the blind data from the universe with the indicated type and index.

Arguments

< type - the blind data type to remove

< index - the index of the blind data packet

Return Codes

sSuccess - the type was found and removed

sFailure - the indicated type could not be found

sInvalidArgument - index was negative

AlChannel* AlUniverse::nextChannel(AlChannel *curChannel )

Description

Returns the next channel in the global list of all channels that appears after the given channel ’curChannel’.

Arguments

< curChannel - the channel in the list to obtain the next channel from

statusCode AlUniverse::nextChannelD(AlChannel *curChannel )

Description

Destructively points ’curChannel’ to the next channel in the global list of all channels that appear after the given channel. sFailure is returned if there is no next channel.

Arguments

< curChannel - the channel in the list to obtain the next channel from

Return Codes

sSuccess - ’curChannel’ now points to the next channel

sFailure - the universe is not initialized or there is no next channel

sInvalidArgument - ’curChannel’ is invalid or NULL

AlAction* AlUniverse::firstAction()

Description

Returns the first action in the list of all actions in the universe. This list is not in any particular order, and in particular, if an action is added to or deleted from the universe, this list may be reordered. Returns NULL if there are no actions in this universe.

AlAction* AlUniverse::nextAction( AlAction *curAction )

Description

Returns the next action in the global list of all actions that appears after the given action ’curAction’. This list is not in any particular order, and in particular, if an action is added to or deleted from the universe, this list may be reordered.

Arguments

< curAction - the action in the list to obtain the next action from

AlLayer* AlUniverse::firstLayer()

Description

Returns the first layer which refers to the default layer. This layer is always valid in the universe. NULL is returned if the universe is not initialized.

AlLayer* AlUniverse::nextLayer(AlLayer *curLayer)

Description

Returns the layer following curLayer in the list of Alias AlLayer objects. NULL is returned if curLayer has no next layer.

Arguments

< curLayer - layer from which to walk forward

statusCode AlUniverse::nextLayerD(AlLayer *curLayer)

Description

Destructively points 'curLayer' to the AlLayer following curLayer in the list of Alias layer objects.

Arguments

< curLayer - layer from which to walk forward

Return Codes

sSuccess - curLayer now points to the next layer

sFailure - there is no next layer

sInvalidArgument - curLayer was invalid

AlLayer *AlUniverse::layerByNumber(int layerID)

Description

Returns a layer object for a given layer number. NULL is returned if the layerID does not exist.

Arguments

< layerID - the number of the layer

boolean AlUniverse::layersEnabled()

Description

Checks if the layer functionality is enabled. True is returned if the functionality is enabled and false otherwise.

statusCode AlUniverse::setLayersEnabled(boolean enable)

Description

Enables or disables the layer functionality temporarily. In the disabled state, the layers are only temporarily disabled. Their attributes and assignment of AlDagNodes restored with enabling layers. While disabling the layers, no information about layers is permanently lost.

Arguments

< enable - a value of true enables the layers and false disables it

Return Codes

sSuccess - the layer was enabled or disabled

sFailure - the layer could not be disabled or enabled

AlShader* AlUniverse::firstShader()

Description

Returns the first AlShader in the list of Alias AlShader objects. NULL is returned if the list is empty.

AlShader* AlUniverse::nextShader( AlShader* curShader )

Description

Returns the AlShader following curShader in the list of Alias AlShader objects. NULL is returned if curShader has no next shader.

Arguments

< curShader - shader from which to walk forward

statusCode AlUniverse::nextShaderD( AlShader* curShader )

Description

Destructively points ’curShader’ to the AlShader following curShader in the list of Alias AlShader objects.

Arguments

< curShader - shader from which to walk forward

Return Codes

sSuccess - curShader now points to the next shader

sFailure - there is no next shader

sInvalidArgument - curShader was invalid

AlPerspectiveCamera* AlUniverse::firstCamera( void )

Description

Returns the first perspective camera.

AlPerspectiveCamera* AlUniverse::nextCamera( AlPerspectiveCamera* curCamera )

Description

Returns the next perspective camera following curCamera in the list of all cameras. NULL is returned if curCamera has no next perspective camera.

Arguments

< curCamera - the camera in the list to obtain the next camera from

statusCode AlUniverse::nextCameraD( AlPerspectiveCamera* curCamera )

Description

Destructively points 'curCamera' to the AlPerspectiveCamera following curCamera in the list of perspective cameras.

Arguments

< curCamera - the camera in the list to obtain the next camera from

Return Codes

sSuccess - curCamera now points to the next camera

sFailure - there is no next camera

sInvalidArgument - curCamera was invalid

AlLocator* AlUniverse::firstLocator()

Description

Returns the first AlLocator in the list of Alias AlLocator objects. NULL is returned if the list is empty.

AlLocator* AlUniverse::nextLocator(AlLocator *curLocator)

Description

Returns the AlLocator following curLocator in the list of Alias AlLocator objects. NULL is returned if curLocator has no next locator.

Arguments

< curLocator - locator from which to walk forward

AlEnvironment* AlUniverse::firstEnvironment()

Description

Returns the first AlEnvironment in the list of Alias AlEnvironment objects. NULL is returned if the list is empty.

statusCode AlUniverse::deleteAll()

Description

Deletes all objects in the universe. After this operation ALL references to ALL objects will be invalid.

Return Codes

sSuccess - everything was successfully deleted

sFailure - the universe was not initialized or the deletion failed

statusCode AlUniverse::deleteAllLocators()

Description

Deletes all locators. After this operation ALL references to ALL AlLocators will be invalid.

Return Codes

sSuccess - everything was successfully deleted

sFailure - the universe was not initialized or the deletion failed

AlConstructionEntity* AlUniverse::firstConstructionEntity()

Description

Returns the first AlConstructionEntity in the list of Alias AlConstructionEntity objects. NULL is returned if the list is empty.

AlConstructionEntity* AlUniverse::nextConstructionEntity(AlConstructionEntity *curConstructionEntity)

Description

Returns the AlConstructionEntity following curConstructionEntity in the list of Alias AlConstructionEntity objects. NULL is returned if curConstructionEntity has no next locator.

Arguments:

< curConstructionEntity - Construction Entity from which to walk forward

statusCode AlUniverse::nextConstructionEntityD(AlConstructionEntity *ce)

Description:

Destructively points ’ce’ to the AlConstructionEntity following ce in the list of Alias AlConstructionEntity objects.

Arguments

< ce - construction entity from which to walk forward

Return Codes

sSuccess - ce now points to the next AlConstructionEntity

sFailure - there is no next AlConstructionEntity

sInvalidArgument - ce was invalid

statusCode AlUniverse::deleteAllConstructionEntities()

Description

Deletes all construction entities. After this operation ALL references to ALL AlConstructionEntities will be invalid.

Return Codes

sSuccess - everything was successfully deleted.

sFailure - the universe was not initialized or the deletion failed.

AlLayer* AlUniverse::firstLayer()

Description

Returns the first layer which refers to the default layer. This layer is always valid in the universe. NULL is returned if the universe is not initialized.

AlLayer* AlUniverse::nextLayer(AlLayer *curLayer)

Description

Returns the layer following curLayer in the list of Alias AlLayer objects. NULL is returned if curLayer has no next layer.

Arguments

< curLayer - layer from which to walk forward

statusCode AlUniverse::nextLayerD(AlLayer *curLayer)

Description

Destructively points 'curLayer' to the AlLayer following curLayer in the list of Alias layer objects.

Arguments

< curLayer - layer from which to walk forward

Return Codes

sSuccess - curLayer now points to the next layer

sFailure - there is no next layer

sInvalidArgument - curLayer was invalid

AlLayer *AlUniverse::layerByNumber(int layerID)

Description

Returns a layer object for a given layer number. NULL is returned if the layerID does not exist.

Arguments

< layerID - the number of the layer

AlLayer * AlUniverse::creationLayer()

Description

Returns the layer object of the creation layer. NULL is returned if the universe if not initialized.

statusCode AlUniverse::setCreationLayer(AlLayer *layer)

Description

Makes the layer a creation layer. When a layer is made a creation layer, all its attributes temporarily become similar to the default layer. For example, an invisible layer becomes visible till it is a creation layer.

Return Codes

sSuccess - the layer was set as a creation layer

sFailure - the layer was not set because either the layer functionality is disabled or the universe is not initialized.

sInvalidArgument - the layer object is not valid.

boolean AlUniverse::layersEnabled()

Description

Checks if the layer functionality is enabled. True is returned if the functionality is enabled and false otherwise.

statusCode AlUniverse::setLayersEnabled(boolean enable)

Description

Enables or disables the layer functionality temporarily. In the disabled state, the layers are only temporarily disabled. Their attributes and assignment of AlDagNode is restored with enabling layers. While disabling the layers, no information about layers is permanently lost.

Arguments

< enable - a value of true enables the layers and false disables it

Return Codes

sSuccess - the layer was enabled or disabled

sFailure - the layer could not be disabled or enabled

statusCode AlUniverse::sortLayersInLayersBar(AlLayerSortMode sortMode)

Description

Sorts the position of layer buttons in the layer bar in the increasing order.

Arguments

< sortMode

kLayerNumber - sort the buttons by their layer number
kLayerName - sort the buttons by their layer name in the lexicographically increasing order

Return Codes

sSuccess - the layer buttons were sorted

sInvalidArgument - the value of sortMode is not valid

sFailure - the universe is not initialized

statusCode AlUniverse::importCloudFile( const char *fileName, int samplingFactor)

Description

Imports a cloud file.

Arguments

< fileName - the name of the cloud file to process

< samplingFactor - controls the sample rate of cloud (a value from 1 to 100)

Return Codes

sInvalidArgument - sampling factor is not from 1 to 100, or fileName is NULL

sSuccess - the cloud file was successfully imported

sFailure - the operation failed or the universe has not been initialized

AlCloud *AlUniverse::firstCloud()

Description

Returns the first cloud in the universe. NULL is returned if the method failed. This method would always fail if the universe has not been initialized.

int AlUniverse::numberOfClouds()

Description

Returns the number of clouds in the universe. The universe must be initialized first for this method to work.

AlBlendCurve* AlUniverse::firstBlendCurve()

Description

Returns the first blend curve in the universe. The universe must be initialized before this method will work.

int AlUniverse::numberOfBlendCurves()

Description

Returns the number of blend curves in the universe. The universe must be initialized first for this method to work

statusCode AlUniverse::redrawScreen( unsigned int flags )

Description

Redraws the modeling windows. Use it after you have completed an operation to see the results. Different parts of the display can be selectively updated by performing a bitwise OR of the following flags:

kRedrawInactive - redraw the inactive objects
kRedrawActive - redraw the active objects
kRedrawTemplate - redraw templated objects
kRedrawWindows - OBSELETE
kRedrawListers - redraw any open editors
kRedrawNone - method will exit without performing any operations

To redraw everything use the following flag:

kRedrawAll = (kRedrawInactive | kRedrawActive | kRedrawTemplate | kRedrawWindows | kRedrawListers )

This routine succeeds in OpenAlias and fails in OpenModel.

Return Codes

sSuccess - able to redraw

sInvalidArgument - flags are out of range

sFailure - unable to redraw (this always occurs in OpenModel)

statusCode AlUniverse::applyIteratorToDagNodes( AlIterator* iter, int& rc )

Description

Applies an iterator to all DAG nodes. This does not recursively go down the DAG.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each dagNode

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToActions( AlIterator* iter, int& rc )

Description

Applies an iterator to each action.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each action

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToChannels( AlIterator* iter, int& rc )

Description

Applies an iterator to each channel.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each channel

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToSets( AlIterator* iter, int& rc )

Description

Applies an iterator to each set.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each set

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToClusters( AlIterator* iter, int& rc )

Description

Applies an iterator to each cluster.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each cluster

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToShaders( AlIterator* iter, int& rc )

Description

Applies an iterator to each shader.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each shader

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToLocators(AlIterator *iter, int &rc)

Description

Applies an iterator to each AlLocator defined in Alias.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each locator

sInvalidArgument - 'iter' was NULL

statusCode AlUniverse::applyIteratorToLayers( AlIterator* iter, int& rc )

Description

Applies an iterator to all layers.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each layer

sInvalidArgument - 'iter' was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToClouds( AlIterator* iter, int& rc )

Description

Applies an iterator to all clouds.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes

sSuccess - the iterator was successfully applied to each cloud

sInvalidArgument - 'iter' was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::applyIteratorToBlendCurves( AlIterator* iter, int& rc )

Description

Applies an iterator to all blend curves.

Arguments

< iter - the iterator to apply

> rc - the return value of the last application of the iterator

Return Codes:

sSuccess - the iterator was successfully applied to each blend curve

sInvalidArgument - ’iter’ was NULL

sFailure - AlUniverse was not initialized

statusCode AlUniverse::writeSDLNoAnimation( const char *filename, boolean store_active )

Description

This method outputs an SDL file for the entire universe if store_active is FALSE. If it is TRUE, then only the active objects in the current universe will be output to a file. In either case no animation will be output; the scene is evaluated at the current view frame which can be set using the AlViewFrame class methods.

Arguments

< filename - the base name of the SDL file to write to (including path if appropriate)

< store_active - as described above

Return Codes

sSuccess - the file(s) was/were successfully written

sFailure - it was not possible to write the SDL file

sInvalidArgument - the filename was NULL

statusCode AlUniverse::writeSDL( const char *filename, boolean store_active, double start, double end, double by )

Description

This method outputs an SDL file for the entire universe if store_active is FALSE. If it is TRUE, then only the active objects in the current universe will be output to a file. Animation will be written to the SDL file for the frame range given. If 'by' is zero then only a single frame will be output.

Arguments

< filename - the base name of the SDL file to write to (including path if appropriate)

< store_active - as described above

< start - the frame to start the animation at

< end - the frame to end the animation at

< by - the increment to get from start to end

Return Codes

sSuccess - the file(s) was/were successfully written

sFailure - it was not possible to write the SDL file

sInvalidArgument - the filename was NULL

double AlUniverse::currentTime()

Description

Used during playback to return the value of the current frame.

statusCode AlUniverse::frameRange(AlFrameRangeType rangeType, double &start, double &end, double &by)

Description

Determines the frame range for the current universe. The range type can be one of kFromPreviewWindow (gets the value from the Preview window, either kMinMax or kGlobal; based on the choice in the preview window - this is undefined for OpenModel), kMinMax (gets the actual start and end as defined by the animaiton on the objects), and kGlobal (gets the values entered by the user - again, undefined for OpenModel).

Arguments

rangeType - as described above

start - frame at which the animation starts

end - frame at which the animation ends

by - the amount by which frames are incremented

Return Codes

sSuccess - the frame range was successfully determined

sInvalidArgument - rangeType was not one of the legal values

AlUniverse::AlApplicationMode AlUniverse::applicationMode()

Description

Returns the current mode that the Alias API is running in (kOpenModel or kOpenAlias). This is useful when writing code that is shared between OpenModel and OpenAlias.

statusCode AlUniverse::userPrefColor( int colorField, int &r, int &g, int &b)

Description

Returns RGB values for the given color field. Color field constants are defined in AlUserColors.h. This method always fails in OpenModel.

Arguments

< colorField - color field

> r - red RGB value

> g - green RGB value

> b - blue RGB value

Return Codes

sSuccess - normal completion

sFailure - an error occurred

statusCode AlUniverse::setUserPrefColor( int colorField, int r, int g, int b)

Description

Sets RGB values for the given color field. Color field constants are defined in AlUserColors.h. This method always fails in OpenModel.

Arguments

< colorField - color field

< r - red RGB value

< g - green RGB value

< b - blue RGB value

Return Codes

sSuccess - normal completion

sFailure - an error occurred

boolean AlUniverse::constructionPlaneInEffect()

Description

Returns TRUE if there is a construction plane in effect.

statusCode AlUniverse::constructionPlaneTransform( AlTM &tm )

Description

Returns the transformation matrix of the construction plane. This matrix will map a point in the construction plane to a point in world space.

Arguments

> tm - matrix where construction plane is returned

Return Codes

sFailure - method failed, or there is no construction plane in effect

sSuccess - the method succeeded

AlCategory* AlUniverse::firstCategory()

Description

Returns the head of the Category structure which is attached to the universe.

This function will return NULL if,

a) The universe is not initialized

b) Layers are not initialized

c) There are no categories

AlCategory* AlUniverse::nextCategory(AlCategory *curCategory)

Description

This method returns the next category in the global list of all categories that appears after the given category ’curCategory’.

Arguments

< curCategory - Category in the list to obtain the next category from