AlCurveOnSurface

Synopsis

#include <AlCurveOnSurface.h>

class AlCurveOnSurface : public AlObject

AlCurveOnSurface();

virtual	~AlCurveOnSurface();

virtual statusCode	deleteObject();

virtual AlObject*	copyWrapper() const;

virtual AlObjectType	type() const;

statusCode	create( int, curveFormType, int, const double[], int, const double[][4] );

statusCode	create( int, const AlCurve*[] );

statusCode	curveOnSurfaceData( double[], double[][4] ) const;

statusCode	realCurveOnSurfaceData( double[], double[][4] ) const;

int	degree() const;

curveFormType	form() const;

int	numberOfSpans() const;

int	numberOfKnots() const;

int	numberOfControlPoints() const;

int	realNumberOfKnots() const;

double	knotValue( int ) const;

statusCode	controlPoint( int, double[4] ) const;

statusCode	setKnotValue( int, double );

statusCode	setControlPoint( int, const double[4] );

boolean	inTrim() const;

boolean	visible() const;

statusCode	setVisible( boolean ) const;

AlSurface*	surface() const;

statusCode	worldSpace3DCopies( int&, AlCurve **& );

statusCode	unaffected3DCopies( int&, AlCurve **& );

statusCode	affected3DCopies( AlTM&, int&, AlCurve **& );

AlCurveOnSurface*	nextCurveOnSurface() const;

AlCurveOnSurface*	prevCurveOnSurface() const;

statusCode	nextCurveOnSurfaceD();

statusCode	prevCurveOnSurfaceD();

statusCode	persistentID( AlPersistentID *&id, int ut = 1 );

statusCode	hasPersistentID( int ut = 1 );

statusCode	setPersistentID( AlPersistentID &, int );

statusCode	insert( double );

statusCode reverse();

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

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

statusCode	removeBlindData( int );

Description

AlCurveOnSurface is the interface to Alias’ curve on surface data objects. Curves on surfaces are created and added to a surface by allocating an AlCurveOnSurface, then calling the create() method, and then calling AlSurfaceNode’s addCurveOnSurface() method to add it to a surface.

Curves on surfaces can also be read in from wire file and modified with this class. Curves on surfaces will be deleted when the surface they are attached to is deleted.

When constructing a curve on surface, you will notice that you need to specify a matrix that has dimensions [numberOfControlPoints][4]. Each point has 4 values, for u, v, zero and w. The “u” and “v” specify the point in U-V parametric space. The third component is zero because this component is not used. The "w" component is the homogeneous value, which is usually 1.0.

See the example programs for an example.

AlCurveOnSurface::AlCurveOnSurface()

Description

Constructs an AlCurveOnSurface wrapper object.

AlCurveOnSurface::~AlCurveOnSurface()

Description

Deletes an AlCurveOnSurface wrapper object.

statusCode AlCurveOnSurface::deleteObject()

Description

Deletes the curve on surface. If it is attached to a surface, it is removed from the surface before it is deleted.

Return Codes

sSuccess - the object was deleted

sInvalidObject - the curve was invalid

AlObject *AlCurveOnSurface::copyWrapper() const

Description

Makes an exact copy of the AlCurveOnSurface wrapper.

AlObjectType AlCurveOnSurface::type() const

Description

Returns the class identifier kCurveOnSurfaceType.

statusCode AlCurveOnSurface::create(int deg,curveFormType form,int numKnots,const double knotVector[],int numControlPts,const double controlPoint[][4] )

Description

Refer to the AlCurve::create() method for information on the meaning and usage of the parameters.

There is one additional constraint placed on this method over and above the AlCurve::create() method. The third component of each control point must be zero, since a curve on surface is expressed only in two dimensions (which is U-V parameter space) plus a homogeneous coordinate (usually 1.0). U and V typically range from 0 to 1.

For any control point [u v 0.0 w], "u" and "v" represent the coordinate in U-V parameter space, and "w" represents the homogeneous coordinate.

Arguments

See the description.

Return Codes

sSuccess - the curve on Surface was created

sInvalidArgument - an invalid or NULL argument was passed

sInsufficientMemory - there was not enough memory to create it

sFailure - the curve could not created

statusCode AlCurveOnSurface::create( int nb_curves, const AlCurve *curves[] )

Description

Creates a Closed Curve On Surface from a loop of AlCurves. This loop will be re-parameterized, so that the loop will be continuous and the form will be set accordingly. If the resulting curve is not physically closed, it is forced closed with all of the start/end points equal.

Arguments

nb_curves - number of curves

curves - array of curves

Return Codes

sInvalidArgument - an invalid or NULL argument was passed

sFailure - the AlCurveOnSurface could not be created

sSuccess - the AlCurveOnSurface was created

statusCode AlCurveOnSurface::curveOnSurfaceData(double knotVector[],double controlPoint[][4] ) const

Description

Assumes that the ’knotVector’ array is of length ’numberOfKnots()’ and the ’controlPoint’ array is of length ’are studying()’ and returns the values of the knots and control points in these arrays.

Note that in the array of control points, each control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesn’t represent anything, and the "w" is the homogeneous coordinate.

Arguments

> knotVector - contains the knots for this curve upon return

> controlPoint - contains the control points upon return

Return Codes

sSuccess - the knotVector & controlPoint data was returned

sInvalidArgument - knotVector or controlPoint was NULL

sInvalidObject - the AlCurveOnSurface was invalid

sFailure - an error occurred

statusCode AlCurveOnSurface::realCurveOnSurfaceData( double knotVector[], double controlPoint[][4] ) const

Description

This method assumes that the ’knotVector’ array is of length ’realNumberOfKnots()’ and the ’controlPoint’ array is of length ’numberOfControlPoints()’ and returns the values of the knots and control points in these arrays.

Note that in the array of control points, each control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesn’t represent anything, and the "w" is the homogeneous coordinate.

Arguments

> knotVector - Contains the knots for this curve upon return.

> controlPoint - Contains the control points upon return.

Return Codes

sSuccess - the knotVector & controlPoint data was returned

sInvalidArgument - knotVector or controlPoint was NULL

sInvalidObject - the AlCurveOnSurface was invalid.

sFailure - an error occurred

int AlCurveOnSurface::degree() const

Description

Returns the degree of the curve. -1 is returned if the curve is not valid.

curveFormType AlCurveOnSurface::form() const

Description

Returns the form of the curve, which is kOpen, kClosed or kPeriodic. If a curve on surface is periodic, it is tangent continuous at the point where it is closed. (If you use the "close" menu item in the interactive Alias package, you actually make a curve periodic.) If a curve is periodic, it implies that it is closed. If a curve is kClosed, then it just means that its endpoints are coincident. Otherwise, the curve is kOpen.

int AlCurveOnSurface::numberOfSpans() const

Description

Returns the number of spans in the curve. This method returns -1 if the curve is invalid.

int AlCurveOnSurface::numberOfKnots() const

Description

Returns the number of knots (just numberOfSpans() + 1). This method returns -1 if the curve is invalid.

int AlCurveOnSurface::realNumberOfKnots() const

Description

Returns the actual number of knots on the curve. That is number_of_spans + 2*degree - 1. A value of -1 will be returned if this method fails.

double AlCurveOnSurface::knotValue( int index ) const

Description

Given a valid knot index, returns the value of the knot in ’knotValue’. A valid knot index is one in the range ’0’ to ’numberOfKnots()-1’.

Arguments

< index - a valid index of the knot value to return

statusCode AlCurveOnSurface::setKnotValue( int index, double knotValue )

Description

Given a valid knot index, sets the value of the knot to be ’knotValue’. A valid knot index is one in the range ’0’ to ’numberOfKnots()-1’.

Arguments

< index - a valid index of the knot value to return

< knotValue - returns the knot value of the given index

Return Codes

sSuccess - the knot value was set

sInvalidArgument - the ’index’ was not in the range 0..#knots-1

sInvalidObject - the curve was invalid

sFailure - the curve was already in a trim

int AlCurveOnSurface::numberOfControlPoints() const

Description

Returns the number of control points.

statusCode AlCurveOnSurface::controlPoint( int index, double point[4] ) const

Description

Given a valid index, returns the value of the control point in ’point’. A valid index is one in the range ’0’ to ’numberOfControlPoints()-1’.

Note the control point is represented by the quadruple [u v 0.0 w], where "u" and "v" represent the control point in U-V parameter space, the "0.0" is unused, and the "w" is the homogeneous coordinate.

Arguments

< index - a valid index of the control point to return

> point - returns the control point at position ’index’

Return Codes

sSuccess - the control point was returned

sInvalidArgument - the index was not valid or ’point’ was NULL

sInvalidObject - the curve was invalid

sFailure - an error occurred

statusCode AlCurveOnSurface::setControlPoint( int index, const double point[4] )

Description

Given a valid index, sets the value of the control point to ’point’. A valid index is one in the range ’0’ to ’numberOfControlPoints()-1’.

Note the control point is represented by a quadruple, [u v 0.0 w] where "u" and "v" represent the control point in U-V parameter space, the "0.0" doesn’t represent anything, and the "w" is the homogeneous coordinate.

Arguments

< index - a valid index of the control point to return

< point - the value to set the control point at position ’index’ to

Return Codes

sSuccess - the control point was set

sInvalidArgument - the index was not valid or ’point’ was NULL

sInvalidObject - the curve was invalid

sFailure - an error occurred

AlSurface* AlCurveOnSurface::surface() const

Description

Returns a pointer to the surface that this curve is on. Otherwise, returns NULL. The surface that this curve-on-surface belongs to MUST have a surface node attached to it.

boolean AlCurveOnSurface::inTrim() const

Description

Returns TRUE if this curve on surface is being used to trim the surface it is on.

boolean AlCurveOnSurface::visible() const

Description

Returns TRUE if the curve is visible (FALSE means the curve is invisible).

statusCode AlCurveOnSurface::setVisible( boolean visible ) const

Description

Sets the visibility on the curve on surface.

Return Codes

sSuccess - The visibility is set as given.

sFailure - The geometry under the curve on surface is invalid.

AlCurveOnSurface* AlCurveOnSurface::nextCurveOnSurface() const

Description

Returns the next curve on surface in the list of curve on surfaces that are attached to a specific surface. Returns NULL if there is no next curve on surface.

statusCode AlCurveOnSurface::nextCurveOnSurfaceD()

Description

Destructively points the wrapper to the next curve on surface in the list of curves on surfaces that are attached to a specific surface.

Return Codes

sSuccess - the wrapper now points to the next CurveOnSurface

sInvalidObject - the curve was invalid

sFailure - there is no next CurveOnSurface

AlCurveOnSurface* AlCurveOnSurface::prevCurveOnSurface() const

Description

Returns the previous curve on surface in the list of curves on surfaces that are attached to a specific surface. Returns NULL if there is no previous curve on surface.

statusCode AlCurveOnSurface::prevCurveOnSurfaceD()

Description

Destructively points the wrapper to the previous curve on surface in the list of curves on surfaces that are attached to a specific surface.

Return Codes

sSuccess - the wrapper now points to the previous CurveOnSurface

sInvalidObject - the curve was invalid

sFailure - there is no previous CurveOnSurface

statusCode AlCurveOnSurface::reverse()

Description

Reverse the direction of this curve on surface.

Return Codes

sInvalidObject - the curve on surface was invalid.

sFailure - the method didn’t succeed.

sSuccess - the direction of the curve on surface was successfully reversed.

statusCode AlCurveOnSurface::insert( double param )

Description

Inserts an edit point into the curve.

Arguments

< param - parametric value of the new edit point on the curve

Return Codes

sSuccess - normal completion

sInvalidArgument - param is out of bounds

sInvalidObject - the given object was not valid

sFailure - an error occurred

statusCode AlCurveOnSurface::worldSpace3DCopies( int& count, AlCurve **&ws_curves )

Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments

> count - the number of curves returned in the curve array

> ws_curves - the array of curves

Return Codes

sSuccess - normal completion

sInvalidObject - the given object was not valid

sFailure - an error occurred

statusCode AlCurveOnSurface::unaffected3DCopies( int& count, AlCurve **&ws_curves )

Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments

> count - the number of curves returned in the curve array

> ws_curves - the array of curves

Return Codes

sSuccess - normal completion

sInvalidObject - the given object was not valid

sFailure - an error occurred

statusCode AlCurveOnSurface::affected3DCopies( AlTM& tm, int& count, AlCurve **&ws_curves )

Description

Returns a pointer via a reference parameter to a temporary curve that represents a world space copy of the curve on surface. The returned curve should be deleted after use. It does not have a parent node and so is not inserted into the DAG hierarchy. tm is the transformation matrix generated while walking the DAG. This method creates cubic world space versions of a curve on surface. As there may be more than one spline returned, a loop of splines is returned (and should be deleted later).

Arguments

> tm - transformation matrix generated by walking the DAG

> count - the number of curves returned in the curve array

> ws_curves - the array of curves

Return Codes

sSuccess - normal completion

sInvalidObject - the given object was not valid

sFailure - an error occurred

statusCode AlCurveOnSurface::persistentID( AlPersistentID *&id, int userType )

Description

Returns a copy of the AlPersistentID associated with this curve on surface. For user type 1, persistent IDs are created if they do not exist already. For all other user types, persistent IDs are not created if they do not exist already, and the method fails. User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments

> id - a copy of the AlPersistentID

< userType - user type of the persistent ID desired.

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

sFailure - the ID did not exist or could not be created

statusCode AlCurveOnSurface::setPersistentID( AlPersistentID &id, int userType )

Description

Sets the values of the AlPersistentID associated with this curve on surface. This method only allows you to create persistent IDs with user types other than 1. If the persistent ID does not exist, it will be created.

User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments

< userType - user type of the persistent ID desired

> id - a copy of the AlPersistentID

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

sInvalidArgument - the given user type is not valid

sFailure - the ID did not exist or could not be created

statusCode AlCurveOnSurface::hasPersistentID( int userType )

Description

Checks to see if the Curve On Surface has a persistent ID associated with it.

Arguments

< userType - user type of the persistent ID desired

Return Codes

sSuccess - the node has a persistent ID

sFailure - the node does not have a persistent ID

sInvalidObject - the given object is not valid

statusCode AlCurveOnSurface::blindData( int userType, long& blindDataSize, const char *&blindData )

Description

Get the blind data packet of the specified type from an AlCurveOnSurface.

Return code

sInvalidObject - the surface was invalid.

sSuccess - blind data successfully retrieved.

sFailure - blind data not found.

statusCode AlCurveOnSurface::setBlindData( int userType, long blindDataSize, const char *blindData )

Description

Add the passed blind data packet to an AlCurveOnSurface.

Return code

sInvalidObject - the surface was invalid.

sSuccess - blind data successfully added.

sFailure - blind data not added

statusCode AlCurveOnSurface::removeBlindData( int user_type )

Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments

< user_type - user type of the blind desired.

Return Codes

sSuccess - everything is okay

sFailure - no such blind data existed

sInvalidObject - the given object is not valid