1 #if !defined( MATHMAP_INCLUDED ) /* Include this file only once */ 2 #define MATHMAP_INCLUDED 3 /* 4 *+ 5 * Name: 6 * mathmap.h 7 8 * Type: 9 * C include file. 10 11 * Purpose: 12 * Define the interface to the MathMap class. 13 14 * Invocation: 15 * #include "mathmap.h" 16 17 * Description: 18 * This include file defines the interface to the MathMap class and 19 * provides the type definitions, function prototypes and macros, 20 * etc. needed to use this class. 21 * 22 * The MathMap class implements Mappings that are specified by a series 23 * of arithmetic expressions that relate output variables to input 24 * variables (and vice versa). 25 26 * Inheritance: 27 * The MathMap class inherits from the Mapping class. 28 29 * Attributes Over-Ridden: 30 * None. 31 32 * New Attributes Defined: 33 * Seed 34 * Random number seed. 35 * SimpFI 36 * Forward-inverse MathMap pairs simplify? 37 * SimpIF 38 * Inverse-forward MathMap pairs simplify? 39 40 * Methods Over-Ridden: 41 * Public: 42 * None. 43 * 44 * Protected: 45 * astClearAttrib 46 * Clear an attribute value for a Frame. 47 * astGetAttrib 48 * Get an attribute value for a Frame. 49 * astMapMerge 50 * Simplify a sequence of Mappings containing a MathMap. 51 * astSetAttrib 52 * Set an attribute value for a Frame. 53 * astTestAttrib 54 * Test if an attribute value has been set for a Frame. 55 * astTransform 56 * Transform a set of points. 57 58 * New Methods Defined: 59 * Public: 60 * None. 61 * 62 * Protected: 63 * astClearSeed 64 * Clear the Seed attribute for a MathMap. 65 * astClearSimpFI 66 * Clear the SimpFI attribute for a MathMap. 67 * astClearSimpIF 68 * Clear the SimpIF attribute for a MathMap. 69 * astGetSeed 70 * Get the value of the Seed attribute for a MathMap. 71 * astGetSimpFI 72 * Get the value of the SimpFI attribute for a MathMap. 73 * astGetSimpIF 74 * Get the value of the SimpIF attribute for a MathMap. 75 * astSetSeed 76 * Set the value of the Seed attribute for a MathMap. 77 * astSetSimpFI 78 * Set the value of the SimpFI attribute for a MathMap. 79 * astSetSimpIF 80 * Set the value of the SimpIF attribute for a MathMap. 81 * astTestSeed 82 * Test whether a value has been set for the Seed attribute of a 83 * MathMap. 84 * astTestSimpFI 85 * Test whether a value has been set for the SimpFI attribute of a 86 * MathMap. 87 * astTestSimpIF 88 * Test whether a value has been set for the SimpIF attribute of a 89 * MathMap. 90 91 * Other Class Functions: 92 * Public: 93 * astIsAMathMap 94 * Test class membership. 95 * astMathMap 96 * Create a MathMap. 97 * 98 * Protected: 99 * astCheckMathMap 100 * Validate class membership. 101 * astInitMathMap 102 * Initialise a MathMap. 103 * astInitMathMapVtab 104 * Initialise the virtual function table for the MathMap class. 105 * astLoadMathMap 106 * Load a MathMap. 107 108 * Macros: 109 * None. 110 111 * Type Definitions: 112 * Public: 113 * AstMathMap 114 * MathMap object type. 115 * 116 * Protected: 117 * AstMathMapVtab 118 * MathMap virtual function table type. 119 120 * Feature Test Macros: 121 * astCLASS 122 * If the astCLASS macro is undefined, only public symbols are 123 * made available, otherwise protected symbols (for use in other 124 * class implementations) are defined. This macro also affects 125 * the reporting of error context information, which is only 126 * provided for external calls to the AST library. 127 128 * Copyright: 129 * Copyright (C) 1997-2006 Council for the Central Laboratory of the 130 * Research Councils 131 132 * Licence: 133 * This program is free software: you can redistribute it and/or 134 * modify it under the terms of the GNU Lesser General Public 135 * License as published by the Free Software Foundation, either 136 * version 3 of the License, or (at your option) any later 137 * version. 138 * 139 * This program is distributed in the hope that it will be useful, 140 * but WITHOUT ANY WARRANTY; without even the implied warranty of 141 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 142 * GNU Lesser General Public License for more details. 143 * 144 * You should have received a copy of the GNU Lesser General 145 * License along with this program. If not, see 146 * <http://www.gnu.org/licenses/>. 147 148 * Authors: 149 * RFWS: R.F. Warren-Smith (Starlink) 150 151 * History: 152 * 3-SEP-1999 (RFWS): 153 * Original version. 154 * 8-JAN-2003 (DSB): 155 * Added protected astInitMathMapVtab method. 156 *- 157 */ 158 159 /* Include files. */ 160 /* ============== */ 161 /* Interface definitions. */ 162 /* ---------------------- */ 163 #include "mapping.h" /* Coordinate mappings (parent class) */ 164 165 #if defined(astCLASS) /* Protected */ 166 #include "channel.h" /* I/O channels */ 167 #include "pointset.h" /* Sets of points/coordinates */ 168 #endif 169 170 /* C header files. */ 171 /* --------------- */ 172 #if defined(astCLASS) /* Protected */ 173 #include <stddef.h> 174 #endif 175 176 /* Macros. */ 177 /* ======= */ 178 /* This value defines the size of an internal table in the AstMathMap 179 data type. Since it will be publicly accessible (but of no external 180 use), we give it an obscure name. */ 181 182 #if defined(astCLASS) || defined(astFORTRAN77) 183 #define STATUS_PTR status 184 #else 185 #define STATUS_PTR astGetStatusPtr 186 #endif 187 #define AST_MATHMAP_RAND_CONTEXT_NTAB_ (32) 188 189 /* Define a dummy __attribute__ macro for use on non-GNU compilers. */ 190 #ifndef __GNUC__ 191 # define __attribute__(x) /*NOTHING*/ 192 #endif 193 194 /* Type Definitions. */ 195 /* ================= */ 196 /* Random number generator context. */ 197 /* -------------------------------- */ 198 /* This structure holds the context for the random number generator 199 used by each MathMap. This ensures that the random number sequences 200 used by different MathMaps are independent, and can be independently 201 controlled by setting/clearing their Seed attributes. Random numbers 202 are produced by combining the output of two internal generators. */ 203 typedef struct AstMathMapRandContext_ { 204 long int rand1; /* State of first internal generator */ 205 long int rand2; /* State of second internal generator */ 206 long int random_int; /* Last random integer produced */ 207 long int table[ AST_MATHMAP_RAND_CONTEXT_NTAB_ ]; /* Shuffle table */ 208 int active; /* Generator has been initialised? */ 209 int seed; /* Seed to be used during initialisation */ 210 int seed_set; /* Seed value set via "Seed" attribute? */ 211 } AstMathMapRandContext_; 212 213 /* MathMap structure. */ 214 /* ------------------ */ 215 /* This structure contains all information that is unique to each 216 object in the class (e.g. its instance variables). */ 217 typedef struct AstMathMap { 218 219 /* Attributes inherited from the parent class. */ 220 AstMapping mapping; /* Parent class structure */ 221 222 /* Attributes specific to objects in this class. */ 223 AstMathMapRandContext_ rcontext; /* Random number generator context */ 224 char **fwdfun; /* Array of forward functions */ 225 char **invfun; /* Array of inverse functions */ 226 double **fwdcon; /* Array of constants for forward functions */ 227 double **invcon; /* Array of constants for inverse functions */ 228 int **fwdcode; /* Array of opcodes for forward functions */ 229 int **invcode; /* Array of opcodes for inverse functions */ 230 int fwdstack; /* Stack size required by forward functions */ 231 int invstack; /* Stack size required by inverse functions */ 232 int nfwd; /* Number of forward functions */ 233 int ninv; /* Number of inverse functions */ 234 int simp_fi; /* Forward-inverse MathMap pairs simplify? */ 235 int simp_if; /* Inverse-forward MathMap pairs simplify? */ 236 } AstMathMap; 237 238 /* Virtual function table. */ 239 /* ----------------------- */ 240 /* This table contains all information that is the same for all 241 objects in the class (e.g. pointers to its virtual functions). */ 242 #if defined(astCLASS) /* Protected */ 243 typedef struct AstMathMapVtab { 244 245 /* Properties (e.g. methods) inherited from the parent class. */ 246 AstMappingVtab mapping_vtab; /* Parent class virtual function table */ 247 248 /* A Unique identifier to determine class membership. */ 249 AstClassIdentifier id; 250 251 /* Properties (e.g. methods) specific to this class. */ 252 int (* GetSeed)( AstMathMap *, int * ); 253 int (* GetSimpFI)( AstMathMap *, int * ); 254 int (* GetSimpIF)( AstMathMap *, int * ); 255 int (* TestSeed)( AstMathMap *, int * ); 256 int (* TestSimpFI)( AstMathMap *, int * ); 257 int (* TestSimpIF)( AstMathMap *, int * ); 258 void (* ClearSeed)( AstMathMap *, int * ); 259 void (* ClearSimpFI)( AstMathMap *, int * ); 260 void (* ClearSimpIF)( AstMathMap *, int * ); 261 void (* SetSeed)( AstMathMap *, int, int * ); 262 void (* SetSimpFI)( AstMathMap *, int, int * ); 263 void (* SetSimpIF)( AstMathMap *, int, int * ); 264 } AstMathMapVtab; 265 266 #if defined(THREAD_SAFE) 267 268 /* Define a structure holding all data items that are global within this 269 class. */ 270 typedef struct AstMathMapGlobals { 271 AstMathMapVtab Class_Vtab; 272 int Class_Init; 273 char GetAttrib_Buff[ 51 ]; 274 } AstMathMapGlobals; 275 276 #endif 277 278 #endif 279 280 /* Function prototypes. */ 281 /* ==================== */ 282 /* Prototypes for standard class functions. */ 283 /* ---------------------------------------- */ 284 astPROTO_CHECK(MathMap) /* Check class membership */ 285 astPROTO_ISA(MathMap) /* Test class membership */ 286 287 /* Constructor. */ 288 #if defined(astCLASS) /* Protected. */ 289 AstMathMap *astMathMap_( int, int, int, const char *[], int, const char *[], 290 const char *, int *, ...); 291 #else 292 AstMathMap *astMathMapId_( int, int, int, const char *[], int, const char *[], 293 const char *, ... )__attribute__((format(printf,7,8))); 294 #endif 295 296 #if defined(astCLASS) /* Protected */ 297 298 /* Initialiser. */ 299 AstMathMap *astInitMathMap_( void *, size_t, int, AstMathMapVtab *, 300 const char *, int, int, 301 int, const char *[], int, const char *[], int * ); 302 303 /* Vtab initialiser. */ 304 void astInitMathMapVtab_( AstMathMapVtab *, const char *, int * ); 305 306 /* Loader. */ 307 AstMathMap *astLoadMathMap_( void *, size_t, AstMathMapVtab *, 308 const char *, AstChannel *, int * ); 309 310 /* Thread-safe initialiser for all global data used by this module. */ 311 #if defined(THREAD_SAFE) 312 void astInitMathMapGlobals_( AstMathMapGlobals * ); 313 #endif 314 315 #endif 316 317 /* Prototypes for member functions. */ 318 /* -------------------------------- */ 319 #if defined(astCLASS) /* Protected */ 320 int astGetSeed_( AstMathMap *, int * ); 321 int astGetSimpFI_( AstMathMap *, int * ); 322 int astGetSimpIF_( AstMathMap *, int * ); 323 int astTestSeed_( AstMathMap *, int * ); 324 int astTestSimpFI_( AstMathMap *, int * ); 325 int astTestSimpIF_( AstMathMap *, int * ); 326 void astClearSeed_( AstMathMap *, int * ); 327 void astClearSimpFI_( AstMathMap *, int * ); 328 void astClearSimpIF_( AstMathMap *, int * ); 329 void astSetSeed_( AstMathMap *, int, int * ); 330 void astSetSimpFI_( AstMathMap *, int, int * ); 331 void astSetSimpIF_( AstMathMap *, int, int * ); 332 #endif 333 334 /* Function interfaces. */ 335 /* ==================== */ 336 /* These macros are wrap-ups for the functions defined by this class 337 to make them easier to invoke (e.g. to avoid type mis-matches when 338 passing pointers to objects from derived classes). */ 339 340 /* Interfaces to standard class functions. */ 341 /* --------------------------------------- */ 342 /* Some of these functions provide validation, so we cannot use them 343 to validate their own arguments. We must use a cast when passing 344 object pointers (so that they can accept objects from derived 345 classes). */ 346 347 /* Check class membership. */ 348 #define astCheckMathMap(this) astINVOKE_CHECK(MathMap,this,0) 349 #define astVerifyMathMap(this) astINVOKE_CHECK(MathMap,this,1) 350 351 /* Test class membership. */ 352 #define astIsAMathMap(this) astINVOKE_ISA(MathMap,this) 353 354 /* Constructor. */ 355 #if defined(astCLASS) /* Protected. */ 356 #define astMathMap astINVOKE(F,astMathMap_) 357 #else 358 #define astMathMap astINVOKE(F,astMathMapId_) 359 #endif 360 361 #if defined(astCLASS) /* Protected */ 362 363 /* Initialiser. */ 364 #define astInitMathMap(mem,size,init,vtab,name,nin,nout,nfwd,fwd,ninv,inv) \ 365 astINVOKE(O,astInitMathMap_(mem,size,init,vtab,name,nin,nout,nfwd,fwd,ninv,inv,STATUS_PTR)) 366 367 /* Vtab Initialiser. */ 368 #define astInitMathMapVtab(vtab,name) astINVOKE(V,astInitMathMapVtab_(vtab,name,STATUS_PTR)) 369 /* Loader. */ 370 #define astLoadMathMap(mem,size,vtab,name,channel) \ 371 astINVOKE(O,astLoadMathMap_(mem,size,vtab,name,astCheckChannel(channel),STATUS_PTR)) 372 #endif 373 374 /* Interfaces to public member functions. */ 375 /* -------------------------------------- */ 376 /* Here we make use of astCheckMathMap to validate MathMap pointers 377 before use. This provides a contextual error report if a pointer 378 to the wrong sort of Object is supplied. */ 379 #if defined(astCLASS) /* Protected */ 380 #define astClearSeed(this) \ 381 astINVOKE(V,astClearSeed_(astCheckMathMap(this),STATUS_PTR)) 382 #define astClearSimpFI(this) \ 383 astINVOKE(V,astClearSimpFI_(astCheckMathMap(this),STATUS_PTR)) 384 #define astClearSimpIF(this) \ 385 astINVOKE(V,astClearSimpIF_(astCheckMathMap(this),STATUS_PTR)) 386 #define astGetSeed(this) \ 387 astINVOKE(V,astGetSeed_(astCheckMathMap(this),STATUS_PTR)) 388 #define astGetSimpFI(this) \ 389 astINVOKE(V,astGetSimpFI_(astCheckMathMap(this),STATUS_PTR)) 390 #define astGetSimpIF(this) \ 391 astINVOKE(V,astGetSimpIF_(astCheckMathMap(this),STATUS_PTR)) 392 #define astSetSeed(this,value) \ 393 astINVOKE(V,astSetSeed_(astCheckMathMap(this),value,STATUS_PTR)) 394 #define astSetSimpFI(this,value) \ 395 astINVOKE(V,astSetSimpFI_(astCheckMathMap(this),value,STATUS_PTR)) 396 #define astSetSimpIF(this,value) \ 397 astINVOKE(V,astSetSimpIF_(astCheckMathMap(this),value,STATUS_PTR)) 398 #define astTestSeed(this) \ 399 astINVOKE(V,astTestSeed_(astCheckMathMap(this),STATUS_PTR)) 400 #define astTestSimpFI(this) \ 401 astINVOKE(V,astTestSimpFI_(astCheckMathMap(this),STATUS_PTR)) 402 #define astTestSimpIF(this) \ 403 astINVOKE(V,astTestSimpIF_(astCheckMathMap(this),STATUS_PTR)) 404 #endif 405 #endif 406 407 408 409 410 411