This function registers a privately-defined coordinate transformation function written in C so that it may be used to create an IntraMap. An IntraMap is a specialised form of Mapping which encapsulates the C function so that it may be used like any other AST Mapping. This allows you to create Mappings that perform any conceivable coordinate transformation.

Registration of relevant transformation functions is required before using the astIntraMap constructor function to create an IntraMap or reading an external representation of an IntraMap from a Channel.

astIntraReg( const char $\ast$name, int nin, int nout, void ($\ast$ tran)( AstMapping $\ast$, int, int, const double $\ast$[], int, int, double $\ast$[] ), unsigned int flags, const char $\ast$purpose, const char $\ast$author, const char $\ast$contact )

name

nin

nout

tran

flags

purpose

author

contact

• Beware that an external representation of an IntraMap (created by writing it to a Channel) will not include the coordinate transformation function which it uses, so will only refer to the function by its name (as assigned using astIntraReg). Consequently, the external representation cannot be utilised by another program unless that program has also registered the same transformation function with the same name using an identical invocation of astIntraReg. If no such registration has been performed, then attempting to read the external representation will result in an error.

• You may use astIntraReg to register a transformation function with the same name more than once, but only if the arguments supplied are identical on each occasion (i.e there is no way of changing things once a function has been successfully registered under a given name, and attempting to do so will result in an error). This feature simply allows registration to be performed independently, but consistently, at several places within your program, without having to check whether it has already been done.

• If an error occurs in the transformation function, this may be indicated by setting the AST error status to an error value (using astSetStatus) before it returns. This will immediately terminate the current AST operation. The error value AST__ITFER is available for this purpose, but other values may also be used (e.g. if you wish to distinguish different types of error).

The following flags are defined in the “ast.h’ ’ header file and allow you to provide further information about the nature of the transformation function. Having selected the set of flags which apply, you should supply the bitwise OR of their values as the “flags’ ’ argument to astIntraReg.

• AST__NOFWD: If this flag is set, it indicates that the transformation function does not implement a forward coordinate transformation. In this case, any IntraMap which uses it will have a TranForward attribute value of zero and the transformation function itself will not be invoked with its “forward’ ’ argument set to a non-zero value. By default, it is assumed that a forward transformation is provided.

• AST__NOINV: If this flag is set, it indicates that the transformation function does not implement an inverse coordinate transformation. In this case, any IntraMap which uses it will have a TranInverse attribute value of zero and the transformation function itself will not be invoked with its “forward’ ’ argument set to zero. By default, it is assumed that an inverse transformation is provided.

• AST__SIMPFI: You may set this flag if applying the transformation function’ s forward coordinate transformation, followed immediately by the matching inverse transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented.

• AST__SIMPIF: You may set this flag if applying the transformation function’ s inverse coordinate transformation, followed immediately by the matching forward transformation, should always restore the original set of coordinates. It indicates that AST may replace such a sequence of operations by an identity Mapping (a UnitMap) if it is encountered while simplifying a compound Mapping (e.g. using astSimplify). It is not necessary that both transformations have actually been implemented.