1 #if !defined( MATRIXMAP_INCLUDED ) /* Include this file only once */ 2 #define MATRIXMAP_INCLUDED 3 /* 4 *+ 5 * Name: 6 * matrixmap.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the MatrixMap class. 13 14 * Invocation: 15 * #include "matrixmap.h" 16 17 * Description: 18 * This include file defines the interface to the MatrixMap class and 19 * provides the type definitions, function prototypes and macros, 20 * etc. needed to use this class. 21 * 22 * The MatrixMap class implements Mappings that transform a set of 23 * coordinates by multiplying them by a matrix. The inverse transformation 24 * can only be applied if the associated matrix is square and non-singular. 25 26 * Inheritance: 27 * The MatrixMap class inherits from the Mapping class. 28 29 * Attributes Over-Ridden: 30 * TranForward (integer) 31 * A read-only boolean value (0 or 1) which indicates whether a 32 * MatrixMap is able to transform coordinates in the "forward" 33 * direction (i.e. converting input coordinates into output 34 * coordinates). 35 * TranInverse (integer) 36 * A read-only boolean value (0 or 1) which indicates whether a 37 * MatrixMap is able to transform coordinates in the "inverse" 38 * direction (i.e. converting output coordinates back into input 39 * coordinates). 40 41 * New Attributes Defined: 42 * None. 43 44 * Methods Over-Ridden: 45 * Public: 46 * None. 47 * 48 * Protected: 49 * astTransform 50 * Apply a MatrixMap to transform a set of points. 51 * astGetTranForward 52 * Determine if a MatrixMap can perform a "forward" coordinate 53 * transformation. 54 * astGetTranInverse 55 * Determine if a MatrixMap can perform an "inverse" coordinate 56 * transformation. 57 58 * New Methods Defined: 59 * Public: 60 * None. 61 * 62 * Protected: 63 * astMtrMult 64 * Multiply a MatrixMap by another MatrixMap. 65 * astMtrRot 66 * Rotate a MatrixMap. 67 68 * Other Class Functions: 69 * Public: 70 * astIsAMatrixMap 71 * Test class membership. 72 * astMatrixMap 73 * Create a MatrixMap. 74 * 75 * Protected: 76 * astCheckMatrixMap 77 * Validate class membership. 78 * astInitMatrixMap 79 * Initialise a MatrixMap. 80 * astInitMatrixMapVtab 81 * Initialise the virtual function table for the MatrixMap class. 82 * astLoadMatrixMap 83 * Load a MatrixMap. 84 85 * Macros: 86 * None. 87 88 * Type Definitions: 89 * Public: 90 * AstMatrixMap 91 * MatrixMap object type. 92 * 93 * Protected: 94 * AstMatrixMapVtab 95 * MatrixMap virtual function table type. 96 97 * Feature Test Macros: 98 * astCLASS 99 * If the astCLASS macro is undefined, only public symbols are 100 * made available, otherwise protected symbols (for use in other 101 * class implementations) are defined. This macro also affects 102 * the reporting of error context information, which is only 103 * provided for external calls to the AST library. 104 105 * Copyright: 106 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 107 * Research Councils 108 109 * Licence: 110 * This program is free software: you can redistribute it and/or 111 * modify it under the terms of the GNU Lesser General Public 112 * License as published by the Free Software Foundation, either 113 * version 3 of the License, or (at your option) any later 114 * version. 115 * 116 * This program is distributed in the hope that it will be useful, 117 * but WITHOUT ANY WARRANTY; without even the implied warranty of 118 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 119 * GNU Lesser General Public License for more details. 120 * 121 * You should have received a copy of the GNU Lesser General 122 * License along with this program. If not, see 123 * <http://www.gnu.org/licenses/>. 124 125 * Authors: 126 * DSB: D.S. Berry (Starlink) 127 128 * History: 129 * 12-Feb-1996 (DSB): 130 * Original version. 131 * 22-Feb-1996 (DSB): 132 * Method "astMatrixRotate" added. 133 * 5-Mar-1996 (DSB): 134 * Method "astMatrixMult" added. 135 * 14-NOV-1996 (DSB): 136 * External interface and I/O added. Public method names shortened. 137 * 3-JUN-1997 (DSB): 138 * astMtrMult and astMtrRot made protected instead of public. 139 * 8-JAN-2003 (DSB): 140 * Added protected astInitMatrixMapVtab method. 141 *- 142 */ 143 144 /* Include files. */ 145 /* ============== */ 146 /* Interface definitions. */ 147 /* ---------------------- */ 148 #include "mapping.h" /* Coordinate mappings (parent class) */ 149 150 #if defined(astCLASS) /* Protected */ 151 #include "pointset.h" /* Sets of points/coordinates */ 152 #include "channel.h" /* I/O channels */ 153 #endif 154 155 /* C header files. */ 156 /* --------------- */ 157 #if defined(astCLASS) /* Protected */ 158 #include <stddef.h> 159 #endif 160 161 /* Macros */ 162 /* ====== */ 163 164 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 165 #ifndef __GNUC__ 166 # define __attribute__(x) /*NOTHING*/ 167 #endif 168 169 /* Type Definitions. */ 170 /* ================= */ 171 /* MatrixMap structure. */ 172 /* ------------------ */ 173 /* This structure contains all information that is unique to each object in 174 the class (e.g. its instance variables). */ 175 typedef struct AstMatrixMap { 176 177 /* Attributes inherited from the parent class. */ 178 AstMapping mapping; /* Parent class structure */ 179 180 /* Attributes specific to objects in this class. */ 181 double *f_matrix; /* Pointer to forward matrix */ 182 double *i_matrix; /* Pointer to inverse matrix */ 183 int form; /* Matrix storage form */ 184 185 } AstMatrixMap; 186 187 /* Virtual function table. */ 188 /* ----------------------- */ 189 /* This table contains all information that is the same for all 190 objects in the class (e.g. pointers to its virtual functions). */ 191 #if defined(astCLASS) /* Protected */ 192 typedef struct AstMatrixMapVtab { 193 194 /* Properties (e.g. methods) inherited from the parent class. */ 195 AstMappingVtab mapping_vtab; /* Parent class virtual function table */ 196 197 /* A Unique identifier to determine class membership. */ 198 AstClassIdentifier id; 199 200 /* Properties (e.g. methods) specific to this class. */ 201 AstMatrixMap *(* MtrRot)( AstMatrixMap *, double, const double[], int * ); 202 AstMatrixMap *(* MtrMult)( AstMatrixMap *, AstMatrixMap *, int * ); 203 204 } AstMatrixMapVtab; 205 206 #if defined(THREAD_SAFE) 207 208 /* Define a structure holding all data items that are global within the 209 object.c file. */ 210 211 typedef struct AstMatrixMapGlobals { 212 AstMatrixMapVtab Class_Vtab; 213 int Class_Init; 214 } AstMatrixMapGlobals; 215 216 217 /* Thread-safe initialiser for all global data used by this module. */ 218 void astInitMatrixMapGlobals_( AstMatrixMapGlobals * ); 219 220 #endif 221 222 223 #endif 224 225 /* Function prototypes. */ 226 /* ==================== */ 227 /* Prototypes for standard class functions. */ 228 /* ---------------------------------------- */ 229 astPROTO_CHECK(MatrixMap) /* Check class membership */ 230 astPROTO_ISA(MatrixMap) /* Test class membership */ 231 232 /* Constructor. */ 233 #if defined(astCLASS) /* Protected. */ 234 AstMatrixMap *astMatrixMap_( int, int, int, const double[], const char *, int *, ...); 235 #else 236 AstMatrixMap *astMatrixMapId_( int, int, int, const double[], const char *, ... )__attribute__((format(printf,5,6))); 237 #endif 238 239 #if defined(astCLASS) /* Protected */ 240 241 /* Initialiser. */ 242 AstMatrixMap *astInitMatrixMap_( void *, size_t, int, AstMatrixMapVtab *, 243 const char *, int, int, int, const double[], int * ); 244 245 /* Vtab initialiser. */ 246 void astInitMatrixMapVtab_( AstMatrixMapVtab *, const char *, int * ); 247 248 /* Loader. */ 249 AstMatrixMap *astLoadMatrixMap_( void *, size_t, AstMatrixMapVtab *, 250 const char *, AstChannel *, int * ); 251 #endif 252 253 /* Prototypes for member functions. */ 254 /* -------------------------------- */ 255 # if defined(astCLASS) /* Protected */ 256 AstMatrixMap *astMtrRot_( AstMatrixMap *, double, const double[], int * ); 257 AstMatrixMap *astMtrMult_( AstMatrixMap *, AstMatrixMap *, int * ); 258 #endif 259 260 /* Function interfaces. */ 261 /* ==================== */ 262 /* These macros are wrap-ups for the functions defined by this class 263 to make them easier to invoke (e.g. to avoid type mis-matches when 264 passing pointers to objects from derived classes). */ 265 266 /* Interfaces to standard class functions. */ 267 /* --------------------------------------- */ 268 /* Some of these functions provide validation, so we cannot use them 269 to validate their own arguments. We must use a cast when passing 270 object pointers (so that they can accept objects from derived 271 classes). */ 272 273 /* Check class membership. */ 274 #define astCheckMatrixMap(this) astINVOKE_CHECK(MatrixMap,this,0) 275 #define astVerifyMatrixMap(this) astINVOKE_CHECK(MatrixMap,this,1) 276 277 /* Test class membership. */ 278 #define astIsAMatrixMap(this) astINVOKE_ISA(MatrixMap,this) 279 280 /* Constructor. */ 281 #if defined(astCLASS) /* Protected. */ 282 #define astMatrixMap astINVOKE(F,astMatrixMap_) 283 #else 284 #define astMatrixMap astINVOKE(F,astMatrixMapId_) 285 #endif 286 287 #if defined(astCLASS) /* Protected */ 288 289 /* Initialiser. */ 290 #define astInitMatrixMap(mem,size,init,vtab,name,nin,nout,form,matrix) \ 291 astINVOKE(O,astInitMatrixMap_(mem,size,init,vtab,name,nin,nout,form,matrix,STATUS_PTR)) 292 293 /* Vtab Initialiser. */ 294 #define astInitMatrixMapVtab(vtab,name) astINVOKE(V,astInitMatrixMapVtab_(vtab,name,STATUS_PTR)) 295 /* Loader. */ 296 #define astLoadMatrixMap(mem,size,vtab,name,channel) \ 297 astINVOKE(O,astLoadMatrixMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 298 #endif 299 300 /* Interfaces to public member functions. */ 301 /* -------------------------------------- */ 302 /* Here we make use of astCheckMatrixMap to validate MatrixMap pointers 303 before use. This provides a contextual error report if a pointer 304 to the wrong sort of Object is supplied. */ 305 306 #if defined(astCLASS) /* Protected */ 307 #define astMtrRot(this,theta,axis) \ 308 astINVOKE(O,astMtrRot_(astCheckMatrixMap(this),theta,axis,STATUS_PTR)) 309 310 #define astMtrMult(this,a) \ 311 astINVOKE(O,astMtrMult_(astCheckMatrixMap(this),astCheckMatrixMap(a),STATUS_PTR)) 312 #endif 313 #endif 314 315 316 317 318 319