AlImagePlane
 
 
 

Interface to Alias image planes.

Synopsis

#include <AlImagePlane.h>
class AlImagePlane : public AlObject , public AlAnimatable , public AlPickable
enum AlDisplayMode {
	kDisplayOff,
	kDisplayUnknown,
	kRGB,
	kColourMap,
	kOutline,
	kFilled
};
enum AlFrameType {
	kFrameOff,
	kRegular,
	kKeyframe
};
union AlFrameTypeParams {
	struct {
		int start;
		int end;
		int by;
		int offset;
	} regular;
	struct {
		int frame;
		double offset;
	} keyframe;
};
enum AlDepthType {
	kDepthOff,
	kDepthUnknown,
	kPriority
};
enum AlMaskType {
	kMaskOff,
	kMaskUnknown,
	kImage,
	kFile,
	kChromaKey
};
union AlMaskTypeParams {
	struct {
		const char *name;
		AlFrameType frameType;
		AlFrameTypeParams *params;
	} file;
	struct {
		double r;
		double g;
		double b;
		double hue_range;
		double sat_range;
		double val_range;
		double threshold;
	} chroma_key;
};
enum AlImageSpaceType {
	kScreen,
	kFields,
	k01,
	kWorld
};
union AlImageSpaceTypeParams {
	struct {
		int size;
	} fields;
	struct {
		int origin_x;
		int origin_y;
		int size_x;
		int size_y;
	} screen;
	struct {
		double tran_x;
		double tran_y;
		double size_x;
		double size_y;
	} zero_one;
	struct {
		double tran_x;
		double tran_y;
		double size_x;
		double size_y;
		double pivot_x;
		double pivot_y;
	} world;
};
struct AlImageSpaceParams {
	boolean wrap_horiz;
	boolean wrap_vert;
	int offset_x;
	int offset_y;
	int coverage_x;
	int coverage_y;
};
	AlImagePlane();
virtual	~AlImagePlane();
virtual AlObject*	copyWrapper() const;
virtual statusCode	deleteObject();
virtual AlObjectType	type() const;
virtual const char*	name() const;
virtual statusCode	setName( const char * );
AlImagePlane*	next() const;
AlImagePlane*	nextInCamera() const;
AlImagePlane*	prev() const;
AlImagePlane*	prevInCamera() const;
statusCode	nextD();
statusCode	nextInCameraD();
statusCode	prevD();
statusCode	prevInCameraD();
const char*	imageFile();
statusCode	setImageFile( const char * );
statusCode	displayMode( AlDisplayMode & );
statusCode	setDisplayMode( AlDisplayMode );
statusCode	RGBMult( double&, double&, double&, double& );
statusCode	setRGBMult( double, double, double, double );
statusCode	RGBOffset( double&, double&, double&, double& );
statusCode	setRGBOffset( double, double, double, double );
statusCode	frameType( AlFrameType&, AlFrameTypeParams* = NULL );
statusCode	setFrameType( AlFrameType, AlFrameTypeParams* = NULL );
statusCode	imageSize( int&, int& );
statusCode	imageData( void*& );
// The next four functions are not fully supported.
statusCode	maskType( AlMaskType&, AlMaskTypeParams* = NULL );
statusCode	setMaskType( AlMaskType, AlMaskTypeParams* = NULL );
statusCode	maskInvert( boolean& );
statusCode	setMaskInvert( boolean );
statusCode	depthType( AlDepthType&, double* = NULL );
statusCode	setDepthType( AlDepthType, double* = NULL );
// The next two functions are not fully supported.
statusCode	imageSpace( AlImageSpaceType, AlImageSpaceTypeParams* = NULL, AlImageSpaceParams* = NULL );
statusCode	setImageSpace( AlImageSpaceType, AlImageSpaceTypeParams* = NULL, AlImageSpaceParams* = NULL );
//	use kScreen X/Y origin to set the position of the image
//	in pixels. Use these to set the pivot (in pixels)
statusCode	pivot( double&, double & );
statusCode	setPivot( double, double );

Description

Image planes are full colour images that are attached to a camera. If the view from that camera is rendered, they get rendered into the background of the resulting image. This class deals with setting the various parameters of image planes and their associations to cameras.

To create an image plane, you must use the addImagePlane function of AlCamera. That function will return to you a new AlImagePlane object that you can use to set the image plane’s parameters. Given a pointer to an AlImagePlane, you can delete it from Alias using the deleteObject method.

To walk the list of all the image planes in Alias, use AlUniverse::firstImagePlane. You can move from image plane to image plane in the current stage or in a camera, by using the appropriate next method.

For more information about image planes in general, see the online documentation for the camera editor.

AlImagePlane::AlImagePlane()

Description

Constructs an AlImagePlane wrapper object.

AlImagePlane::~AlImagePlane()

Description

Deletes an AlImagePlane wrapper object.

AlObject* AlImagePlane::copyWrapper() const

Description

Makes a copy of the AlImagePlane. The returned AlCamera will reference the same data as the original.

AlObjectType AlImagePlane::type() const

Description

Returns the class identifier kImagePlaneType.

statusCode AlImagePlane::deleteObject()

Description

Deletes the image object.

AlImagePlane* AlImagePlane::next() const

Description

Returns the next image plane in the universe.

AlImagePlane* AlImagePlane::nextInCamera() const

Description

Returns the next ImagePlane in the who universe, no for the given camera. The best way to walk the ImagePlanes for a camera is AlCamera::applyIteratorToImagePlanes.

AlImagePlane* AlImagePlane::prev() const

Description

Returns the previous ImagePlane in the who universe.

AlImagePlane* AlImagePlane::prevInCamera() const

Description

Returns the previous ImagePlane in the universe for the given camera. The best way to walk the ImagePlanes for a camera is AlCamera::applyIteratorToImagePlanes.

statusCode AlImagePlane::nextD()

Description

Returns the next ImagePlane in the universe by pointing the current wrapper to the next image plane object.

Return Codes

sSuccess - the wrapper now points to the next object

sFailure - there is no next imageplane

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::nextInCameraD()

Description

Returns the next ImagePlane in the universe that is associated with the same camera. The current wrapper will now point to the next image plane object in the list.

Return Codes

sSuccess - the wrapper now points to the next object

sFailure - there is no next imageplane

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::prevD()

Description

Returns the previous ImagePlane in the universe by pointing the current wrapper to the previous image plane object.

Return Codes

sSuccess - the wrapper now points to the previous object

sFailure - there is no previous imageplane before the current one

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::prevInCameraD()

Description

Returns the previous ImagePlane in the universe that is associated with the same camera. The current wrapper will now point to the previous image plane object in the list.

Return Codes

sSuccess - the wrapper now points to the previous object

sFailure - there is no next imageplane

sInvalidObject - the image plane was invalid

const char* AlImagePlane::name() const

Description

Returns the name of the image plane.

statusCode AlImagePlane::setName( const char * newName )

Description

Sets the name of the image plane.

Arguments

< newName - the new name for the image plane

Return Codes

sSuccess - the name was set

sFailure - the name could not be changed

const char* AlImagePlane::imageFile()

Description

Returns the filename of the image plane.

statusCode AlImagePlane::setImageFile( const char * name )

Description

Sets the filename of the image plane.

Arguments

< newName - the new filename for the image plane

Return Codes

sSuccess - the name was set

sFailure - the name could not be changed

statusCode AlImagePlane::displayMode( AlDisplayMode & dm )

Description

Returns the display mode of the image plane.

Arguments

> dm - the variable to place the result in

Return Codes

sSuccess - the display mode was returned

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::setDisplayMode( AlDisplayMode dm )

Description

Sets the display mode of the image plane. The available display modes are kDisplayOff, kRGB, kColourMap, kOutline, kFilled

Arguments

< dm - the new display mode

Return Codes

sSuccess - the display mode was set

sInvalidArgument - an unknown display mode was specified

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::RGBMult( double& r, double& g, double& b, double& a )

Description

Returns the RGBA multipliers of the image plane. Values of 1,1,1,1 will produce no change. 0,0,0,0 will result in a black image.

Arguments

> r,g,b,a - the returned red, green, blue and alpha values

Return Codes

sSuccess - the multipliers were retrieved

sInvalidObject - the image plane was invalid

sFailure - the rgba values could not be read

statusCode AlImagePlane::setRGBMult( double r, double g, double b, double a)

Description

Sets the RGB multiplier of the image plane.

Arguments

< r,g,b,a - the new red, green, blue and alpha values

Return Codes

sSuccess - the multipliers were set

sInvalidObject - the image plane was invalid

sFailure - the rgba values could not be set

statusCode AlImagePlane::RGBOffset( double& r, double& g, double& b, double& a )

Description

Returns the RGBA offsets of the image plane. These values are added to each RGBA value.

Arguments

> r,g,b,a - the returned red, green, blue and alpha values

Return Codes

sSuccess - the offset was retrieved

sInvalidObject - the image plane was invalid

sFailure - the rgba values could not be read

statusCode AlImagePlane::setRGBOffset( double r, double g, double b, double a )

Description

Sets the RGB multiplier of the image plane.

Arguments

< r,g,b,a - the red, green, blue and alpha values

Return Codes

sSuccess - the multipliers were set

sInvalidObject - the image plane was invalid

sFailure - the rgba values could not be set

statusCode AlImagePlane::frameType(AlFrameType& ft,AlFrameTypeParams* ftp)

Description

Returns the frame type parameters of the image plane.

Arguments

> ft - the returned type of the frame parameters

> ftp - the returned values for the parameters

Return Codes

sSuccess - the parameters were retrieved

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be retrieved

statusCode AlImagePlane::setFrameType(AlFrameType ft,AlFrameTypeParams* ftp )

Description

Sets the frame type parameters of the image plane. The frame type must be one of kFrameOff, kRegular or kKeyframe.

Arguments

< ft - the type of the frame parameters

< ftp - the values for the parameters

Return Codes

sSuccess - the parameters were set

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be set

sInvalidArgument - an invalid frame type was given

statusCode AlImagePlane::imageSize( int& x, int& y )

Description

Returns the width and height in pixels of the underlying image.

statusCode AlImagePlane::imageData( void*& data )

Description

Returns a pointer to the internal image data. The size of the data referenced by the pointer can be determined from imageSize(x,y) above and the type of image. If it is an RGB image the number of bytes in the image is 4 * x * y. The data should be treated as read only.

Note: Under no circumstances should the returned pointer be freed.

statusCode AlImagePlane::maskType(AlMaskType& mt,AlMaskTypeParams* mtp )

Description

Returns the mask type parameters of the image plane.

Arguments

> ft - the returned type of the mask parameters

> ftp - the returned values for the parameters

Return Codes

sSuccess - the parameters were retrieved

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be retrieved

statusCode AlImagePlane::setMaskType(AlMaskType mt,AlMaskTypeParams* mtp )

Description

Sets the mask type parameters of the image plane. The frame type must be one of kMaskOff, kImage, kKeyframe or kFile.

Arguments

< ft - the type of the mask parameters

< ftp - the values for the parameters

Return Codes

sSuccess - the parameters were set

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be set

sInvalidArgument - an invalid mask type was given

statusCode AlImagePlane::maskInvert( boolean& b )

Description

Returns the state of the mask invert flag.

Arguments

> b - the returned state of the flag

Return Codes

sSuccess - the state was returned

sInvalidObject - the image plane was invalid

statusCode AlImagePlane::setMaskInvert( boolean b )

Description

Sets the state of the mask invert flag.

Arguments

< b - the new state of the flag

Return Codes

sSuccess - the state was set

sInvalidObject - the image plane was invalid

sFailure - the flag could not be set

statusCode AlImagePlane::depthType(AlDepthType& dt,double* depth )

Description

Returns the state and value of the depth type.

Arguments

> dt - the returned depth type

> depth - a pointer to a variable to place the depth (if not NULL)

Return Codes

sSuccess - the type was returned

sInvalidObject - the image plane was invalid

sFailure - the type could not be determined

statusCode AlImagePlane::setDepthType(AlDepthType dt,double* depth )

Description

Sets the state and value of the depth type.

Arguments

< dt - the new depth type

< depth - if non-NULL, then this points to the value of the depth

Return Codes

sSuccess - the depth type was returned

sInvalidObject - the image plane was invalid

sFailure - the depth type could not be set

statusCode AlImagePlane::imageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams )

Description

Returns the parameters of the image plane (refer to the camera editor for more details). Use the spaceType to denote the type of parameters that you are requesting information on.

This can be kFields (if the image is in the perspective window), k01, kScreen or kWorld.

Arguments

< spaceType - the space type parameters to return

> spaceTypeParams - the returned values of the space type

> spaceParams - the returned values of the wrap and origin values

Return Codes

sSuccess - the parameters were returned

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be read

statusCode AlImagePlane::setImageSpace(AlImageSpaceType spaceType,AlImageSpaceTypeParams* spaceTypeParams,AlImageSpaceParams* spaceParams )

Description

Sets the parameters of the image plane. The spaceType must be one of kFields, kScreen, kWorld, k01. (This denotes the set of parameters that you want to set. Several calls to this routine may be required to set all of the parameters. Please refer to the camera editor for more details).

Note that world space is only allowed in orthographic windows but not in perspective windows.

Arguments

< spaceType - the set of space parameters to set

< spaceTypeParams - the new values of the space type

< spaceParams - the new values of the wrap and origin values

Return Codes

sSuccess - the parameters were set

sInvalidObject - the image plane was invalid

sFailure - the parameters could not be set