Encapsulates access to Reference Files.

Synopsis

enum ReferenceFileStatus
{    
    kFileNotFound,    
    kStale,    
    kUpToDate,    
    kSourceWireNotFound,    
    kError 
};

class STUDIOAPI_DECL AlReferenceFile : public AlObject

{

public:    
    typedef struct UUID { unsigned int x[4]; } UUID;    
    virtual                    ~AlReferenceFile();

       virtual statusCode        deleteObject();
       virtual AlObject*          copyWrapper() const;

       virtual AlObjectType    type() const;

       virtual const char*        name() const;    
    const char*                fileName() const;    
    const char*                sourceWirefile() const;    
    UUID                 getUuid() const;

    ReferenceFileStatus     status() const;

    double                  curveTolerance() const;
    double                  surfaceTolerance() const;
    int                     numLayers() const;
    int                     numComponents() const;

    bool                    isInstance() const;
    bool                    isVisible() const;
    statusCode              setVisible(bool isVisible);
    bool                    hasColour() const;
    bool                    getColour(unsigned char rgba[4]) const;
    statusCode              setColour(unsigned char rgba[4]);

                statusCode localTransformationMatrix( double[4][4] ) const;    
                statusCode globalTransformationMatrix( double[4][4] ) const;        
                statusCode inverseGlobalTransformationMatrix( double[4][4] ) const;

    statusCode localTransformationMatrix( AlTM& ) const;        
    statusCode globalTransformationMatrix( AlTM& ) const;        
    statusCode inverseGlobalTransformationMatrix( AlTM& ) const;

    statusCode translation( double&, double&, double& ) const;    
    statusCode rotation( double&, double&, double& ) const;    
    statusCode scale( double&, double&, double& ) const;     
    statusCode rotatePivot( double&, double&, double& ) const;    
    statusCode scalePivot( double&, double&, double& ) const;

    statusCode setTranslation( double, double, double );    
    statusCode setWorldTranslation( double, double, double );    
    statusCode setRotation( double, double, double );    
    statusCode setScale( double, double, double );

    statusCode setRotatePivot( double, double, double );    
    statusCode setScalePivot( double, double, double );

    statusCode copyTransform( AlReferenceFile* other );

    AlReferenceObject*      firstObject() const;    
    statusCode              nextObjectD( AlReferenceObject* ) const;    
    AlShader*               firstShader() const;    
    statusCode              nextShaderD( AlShader* ) const;

    AlReferenceLayer*       getLayer( int num ) const;    
    AlReferenceFileSet*     getOwner() const;

    AlReferenceFile*        getParentReference() const;


    AlReferenceFile*        firstChildReference() const;    
    statusCode              nextChildReferenceD( AlReferenceFile* ) const;    
    statusCode              addChildReference( AlReferenceFile* );

    static AlReferenceFile* createEmptyReference( const char* source );


};

END FILE SOURCE

Class Description

AlReferenceFile is an interface to the Reference Files and Reference File Alternatives that are contained in the Alias Reference Manager. They are accessed through AlReferenceFileSet.

Instances of this class can be used to access properties applied to the Reference Files, such as visibility, draw colour, and transform; it can also be used to access data belonging to the Reference File, including the objects, layers, and shaders, as well as the Reference File hierarchy for Reference assemblies.

statusCode AlReference::deleteObject()

Description

Delete the associated Reference File from Alias.

Return Codes

sSuccess - the AlReferenceFile data was successfully deleted.

sInvalidObject - the AlReferenceFile was not valid.

sFailure - error deleting the Reference File; it may have already been deleted

AlObject* AlReference::copyWrapper() const

Makes a copy of the AlReferenceFile. The returned AlReference references the same data as the original.

AlObjectType AlReference::type() const

Description

Returns the class identifier kReferenceFileType.

const char* AlReference::name() const

Description

Returns the name of the Reference File, as shown in the Reference Manager.

const char* AlReference::filename() const

Description

Returns the file path of the WREF associated with the Reference File.

Returns nullptr if the AlReferenceFile is invalid.

const char* AlReference::sourceWirefile() const

Description

Returns the file path of the source file which was used to create the Reference File.

Returns nullptr if the AlReferenceFile is invalid.

ReferenceFileStatus AlReference::status() const

Description

Query the status of the Reference File.

Returns nullptr if the AlReferenceFile is invalid.

Return Codes (ReferenceFileStatus enum)

kFileNotFound - the WREF cannot be found.

kStale - the source file has been modified since the WREF was created, or since the WREF was loaded in the case that the WREF is modified without updating this Reference File.

kUpToDate - The data in the Reference File is up to date with the source file.

kSourceWireNotFound - the source file cannot be found.

kError - Error checking the status; AlReferenceFile was not valid or error querying the WREF or Source files.

double AlReference::curveTolerance() const

Description

Returns the curve tessellation tolerance used to create the WREF.

double AlReference::surfaceTolerance() const

Description

Returns the surface tessellation tolerance used to create the WREF.

int AlReference::numLayers() const

double surfaceTolerance() const

Description

Returns the number of layers in the Reference File.

int AlReference::numComponents() const

Description

Returns the number of objects in the Reference File.

bool AlReference::isInstance() const

Description

Query whether the associated Reference File is an instance of another Reference File. This is true for Alternatives.

bool AlReference::isVisible() const

Description

Returns true if the visibility is set for the associated Reference File. There may be an overriding visibility on the containing Reference File Set, or on a parent Reference File in the Reference assembly case.

statusCode AlReference::setVisible( bool flag )

Description

Set the visibility of the associated Reference File. Overriding visibilies should be considered if using this.

Return Codes

sSuccess - successfully set the visibility.

sFailure - Failed to set the visibility; AlReferenceFile was invalid.

bool AlReference::hasColour() const

Description

Returns whether the associated Reference File has a custom draw colour set. Note that this only queries the associated Reference File itself, and does not consider overriding colours from Reference File Sets or parent Reference Files in Reference assemblies.

bool AlReference::getColor( unsigned char rgba[4] ) const

Description

Returns whether the associated Reference File has a custom draw colour set. Note that this only queries the associated Reference File itself, and does not consider overriding colours from Reference File Sets or parent Reference Files in Reference assemblies.

Return Values

true - The colour was successfully retrieved.

false - The AlReferenceFile was invalid or the associated Reference File does not have a custom colour.

statusCode AlReference::setColor( unsigned char rgba[4] )

Description

Set the custom colour on the associated Reference File. Note that this only queries the associated Reference File itself, and does not consider overriding colours from Reference File Sets or parent Reference Files in Reference assemblies.

Return Codes

sSuccess - successfully set the color.

sFailure - error setting colour; AlReferenceFile was invalid.

statusCode AlReference::localTransformationMatrix( double[4][4] ) const

Description

Get the transformation applied to the associated Reference File. Data is set in argument. This returns the local transformation only; there may be additional transformations from the Reference File Set or parent Reference Files in Reference assemblies.

Return Codes

sSuccess - successfully retrieved transform.

sInvalidObject - the AlReferenceFile is invalid.

sInvalidArgument - the matrix argument was null.

statusCode AlReference::globalTransformationMatrix( double[4][4] ) const

Description

Get the total transformation applied to the associated Reference File, including transformations from Reference File Sets and parent Reference Files. Data is set in argument.

Return Codes

sSuccess - successfully retrieved transform.

sInvalidObject - the AlReferenceFile is invalid.

sInvalidArgument - the matrix argument was null.

statusCode AlReference::inverseGlobalTransformationMatrix( double[4][4] ) const

Description

Get the total inverse transformation applied to the associated Reference File, including transformations from Reference File Sets and parent Reference Files. Data is set in argument.

Return Codes

Success - successfully retrieved transform.

sInvalidObject - the AlReferenceFile is invalid.

sInvalidArgument - the matrix argument was null.

statusCode AlReference::translation( double&, double&, double& ) const

Description

Same as above but for AlTM arguments.

Arguments

All arguments are output, order is x,y,z.

Return Codes

sSuccess - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::rotation( double&, double&, double& ) const

Description

Same as above but for AlTM arguments.

Arguments

All arguments are output, order is x,y,z.

Return Codes

sSuccess - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::scale( double&, double&, double& ) const

Description

Same as above but for AlTM arguments.

Arguments

All arguments are output, order is x,y,z.

Return Codes

sSuccess - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::rotatePivot( double&, double&, double& ) const

Description

Same as above but for AlTM arguments.

Arguments

All arguments are output, order is x,y,z.

Return Codes

sSuccess - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::scalePivot( double&, double&, double& ) const

Description

Same as above but for AlTM arguments.

Arguments

All arguments are output, order is x,y,z.

Return Codes

sSuccess - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setTranslation( double, double, double )

Description

Set individual components of the local transformation.

Arguments

x,y,z values for desired transformation component.

Return Codes:

Success - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setRotation( double, double, double )

Description

Set individual components of the local transformation.

Arguments

x,y,z values for desired transformation component.

Return Codes:

Success - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setScale( double, double, double )

Description

Set individual components of the local transformation.

Arguments

x,y,z values for desired transformation component.

Return Codes:

Success - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setRotatePivot( double, double, double )

Description

Set individual components of the local transformation.

Arguments

x,y,z values for desired transformation component.

Return Codes:

Success - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setScalePivot( double, double, double )

Description

Set individual components of the local transformation.

Arguments

x,y,z values for desired transformation component.

Return Codes:

Success - successfully retrieved the transformation values.

sInvalidObject - the AlReferenceFile was invalid.

statusCode AlReference::setWorldTranslation( double, double, double )

Description

Set the desired absolute position for the associated Reference File. This will compute the translation necessary to place the Reference File at the provided world coordinates. Arguments: x,y,z world coordinates to place the Reference File.

statusCode AlReference::copyTransform( AlReferenceFile* other )

Description

Set the transformation of the associated Reference File from the transformation on other. Arguments:

Arguments

other - AlReferenceFile wrapper of the Reference File to copy transform from.

AlReferenceObject* AlReference::firstObject() const

Description

Create and return a wrapper for the first object in the Reference File. Returns nullptr if the AlReferenceFile not loaded or contains no objects.

Description: Return Codes: sSuccess - successfully advanced the AlReferenceObject sFailure - failed to advance the AlReferenceObject; either the AlReferenceFile isInstance invalid or the AlReferenceObject was the last in the file

statusCode AlReference::nextObjectD( AlReferenceObject* ) const

Description

Move the AlReferenceObject wrapper to the next object in the Reference File.

Return Codes

sSuccess - successfully advanced the AlReferenceObject.

sFailure - failed to advance the AlReferenceObject; either the AlReferenceFile isInstance invalid or the AlReferenceObject was the last in the file.

AlShader* AlReference::firstShader() const

Description

Create and return a wrapper for the first shader in the Reference File. Returns nullptr if the AlReferenceFile contains no shaders.

statusCode AlReference::nextShaderD( AlShader* ) const

Description

Move the AlShader wrapper to the next shader in the Reference File.

Return Codes

sSuccess - successfully advanced the AlShader.

sFailure - failed to advance the AlShader; either the AlReferenceFile isInstance invalid or the AlShader was the last in the file.

AlReferenceLayer* AlReference::getLayer( int num ) const

Description

Create and return a wrapper for the num'th layer in the Reference File.

AlReferenceFileSet* AlReference::getOwner() const

Description

Create and return a wrapper to the Reference File Set which contains this Reference File.

AlReferenceFile* AlReference::getParentReference() const

Description

Create and return a wrapper to the Reference File above this one in the Reference assembly structure. Returns nullptr if this Reference File is at the top of the structure.

AlReferenceFile* AlReference::firstChildReference() const

Description

Create and return a wrapper for the first Reference File below this one in the Reference assembly structure. Returns nullptr if the Reference File has no children.

statusCode AlReference::nextChildReferenceD( AlReferenceFile* ) const

Description

Move the AlReferenceFile wrapper to the next child reference of this Reference File.

Return Codes

sSuccess - successfully advanced the AlReferenceFile argument.

sInvalidObject - this AlReferenceFile is invalid.

sInvalidArgument - the argument AlReferenceFile is invalid, or is not a child of this.

statusCode AlReference::addChildReference( AlReferenceFile* )

Description

Add a Reference File as a child to this Reference File. This can be used to build a Reference assembly structure. If the Reference File associated with this wrapper is updated, then during that update Alias will try to copy properties from any children that can be matched after the update. This allows you to build up an assembly structure using createEmptyReference of empty Reference Files, an set properties such as visibility and colours on the Reference Files in the structure. Then in Alias you would see a file structure in the Reference Manager which is not loaded. In Alias users could then update the top reference, and if the actual structure matches the that created using this method, those properties will be preserved while Alias generates the WREF files and imports them.

static AlReferenceFile* AlReferenceFile::createEmptyReference( const char* source )

Description

Creates an empty Reference File for the provided source path. This can be used as a placeholder Reference File, which can have properties applied such as visibility and transformations, without actually converting the source to WREF and loading it. This can be used to prepare a stage in Alias with Reference Files, and delay the conversion and import of the source file to be done through the Reference Manager.