1 /***********************************************************************/ 2 /* Open Visualization Data Explorer */ 3 /* (C) Copyright IBM Corp. 1989,1999 */ 4 /* ALL RIGHTS RESERVED */ 5 /* This code licensed under the */ 6 /* "IBM PUBLIC LICENSE - Open Visualization Data Explorer" */ 7 /***********************************************************************/ 8 9 10 #if defined(__cplusplus) || defined(c_plusplus) 11 extern "C" { 12 #define private __private__ 13 #endif 14 15 #ifndef _DXI_OBJECT_H_ 16 #define _DXI_OBJECT_H_ 17 18 /* TeX starts here. Do not remove this comment. */ 19 20 /* 21 \section{Object class} 22 \label{objectsec} 23 \paragraph{Type definitions.} 24 An object is represented by a pointer to a C structure stored in global 25 memory. The content of the structure is private to the implementation. 26 A {\tt typedef} is provided for each class of object: 27 */ 28 typedef struct object *Object; 29 typedef struct private *Private; 30 typedef struct string *String; 31 typedef struct field *Field; 32 typedef struct group *Group; 33 typedef struct series *Series; 34 typedef struct compositefield *CompositeField; 35 typedef struct array *Array; 36 typedef struct sharedarray *SharedArray; 37 typedef struct regulararray *RegularArray; 38 typedef struct constantarray *ConstantArray; 39 typedef struct patharray *PathArray; 40 typedef struct productarray *ProductArray; 41 typedef struct mesharray *MeshArray; 42 typedef struct interpolator *Interpolator; 43 typedef struct xform *Xform; 44 typedef struct screen *Screen; 45 typedef struct clipped *Clipped; 46 typedef struct camera *Camera; 47 typedef struct light *Light; 48 typedef struct multigrid *MultiGrid; 49 /* 50 An {\tt enum} provides a number for each class and subclass: 51 */ 52 typedef enum { 53 CLASS_MIN, 54 CLASS_OBJECT, 55 CLASS_PRIVATE, 56 CLASS_STRING, 57 CLASS_FIELD, 58 CLASS_GROUP, 59 CLASS_SERIES, 60 CLASS_COMPOSITEFIELD, 61 CLASS_ARRAY, 62 CLASS_REGULARARRAY, 63 CLASS_PATHARRAY, 64 CLASS_PRODUCTARRAY, 65 CLASS_MESHARRAY, 66 CLASS_INTERPOLATOR, 67 CLASS_FIELDINTERPOLATOR, 68 CLASS_GROUPINTERPOLATOR, 69 CLASS_LINESRR1DINTERPOLATOR, 70 CLASS_LINESII1DINTERPOLATOR, 71 CLASS_LINESRI1DINTERPOLATOR, 72 CLASS_QUADSRR2DINTERPOLATOR, 73 CLASS_QUADSII2DINTERPOLATOR, 74 CLASS_TRISRI2DINTERPOLATOR, 75 CLASS_CUBESRRINTERPOLATOR, 76 CLASS_CUBESIIINTERPOLATOR, 77 CLASS_TETRASINTERPOLATOR, 78 CLASS_FLE2DINTERPOLATOR, 79 CLASS_GROUPITERATOR, 80 CLASS_ITEMITERATOR, 81 CLASS_XFORM, 82 CLASS_SCREEN, 83 CLASS_CLIPPED, 84 CLASS_CAMERA, 85 CLASS_LIGHT, 86 CLASS_CONSTANTARRAY, 87 CLASS_MULTIGRID, 88 CLASS_SHAREDARRAY, 89 CLASS_MAX, 90 CLASS_DELETED 91 } Class; 92 93 /* 94 \paragraph{Classes and subclasses.} Subclasses are handled as 95 follows, taking the {\tt Group} class as an example. The {\tt 96 DXGetObjectClass()} routine returns the subclass of {\tt Object} ({\tt 97 CLASS\_GROUP}, for example) so that a user whose operation does not 98 depend on the specific subclass is not affected. For each class that 99 is subclassed, there is a {\tt Get...Class()} routine ({\tt 100 DXGetGroupClass()}, for example) to determine the subclass. Objects of 101 the superclass ({\tt Group}, for example) may still be created and 102 manipulated using the generic superclass manipulation routines ({\tt 103 DXNewGroup()} and {\tt DXSetMember()} for example). In such a case, the 104 {\tt Get...Class()} routine will return the name of the superclass; 105 thus, for example, {\tt DXGetGroupClass()} may return {\tt CLASS\_GROUP} 106 if the object is a generic group, or {\tt CLASS\_COMPOSITEFIELD} etc. 107 if it is an object of one of the subclasses of the group class. The 108 subclass identifiers ({\tt CLASS\_COMPOSITEFIELD etc.}) are in the 109 same {\tt enum} as the class identifiers ({\tt CLASS\_GROUP}, etc.). 110 111 \paragraph{Object routines.} 112 There are a number of routines common to all objects. These include 113 routines for reserving a reference to an object, for deleting an 114 object, and for saving an object to and restoring it from a file. 115 */ 116 117 Class DXGetObjectClass(Object o); 118 /** 119 \index{DXGetObjectClass} 120 Returns the class of an object, to be interpreted according to the 121 definitions given above. 122 **/ 123 124 Object DXReference(Object o); 125 /** 126 \index{DXReference} 127 Indicates that there is a reference to object {\tt o}. The object is 128 guaranteed to not be deleted until this reference is released, via the 129 {\tt DXDelete} routine. When an object is first created, it has zero 130 references. Returns {\tt o}, or returns null and sets the 131 error code to indicate an error. 132 **/ 133 134 Error DXDelete(Object o); 135 /** 136 \index{DXDelete} 137 Indicates that a previous reference to object {\tt o} (signified by 138 {\tt DXReference()}) no longer exists. When no further references to an 139 object exist, all storage associated with the object will be deleted. 140 Returns {\tt OK} to indicate success, or returns {\tt ERROR} and sets 141 the error code to indicate an error. 142 **/ 143 144 Error DXUnreference(Object o); 145 /** 146 \index{DXUnreference} 147 Special routine -- DXDelete is the normal way to remove a reference to 148 an object. If the reference count should be decremented to zero but 149 the object should NOT be deleted, this routine can be used instead of 150 DXDelete. 151 **/ 152 153 int DXGetObjectTag(Object o); 154 Object DXSetObjectTag(Object o, int tag); 155 /** 156 \index{DXGetObjectTag}\index{DXSetObjectTag} 157 Every object is assigned a unique non-zero integer tag when it is 158 created. In addition, the executive sets the object tag of objects it 159 knows about by using {\tt DXSetObjectTag()}. This tag is used, for 160 example, by the cache system to identify objects. {\tt DXGetObjectTag()} 161 returns the object identifier, or returns 0 and sets the error code 162 to indicate an error. 163 **/ 164 165 Object DXSetAttribute(Object o, char *name, Object value); 166 /** 167 \index{DXSetAttribute} 168 Every object may have associated with it a set of {\em attributes}, in 169 the form of name/value pairs. This routine sets attribute {\tt name} 170 for object {\tt o} to {\tt value}. Returns {\tt o} on success, or returns null 171 and sets the error code to indicate an error. 172 **/ 173 174 Object DXDeleteAttribute(Object o, char *name); 175 /** 176 \index{DXDeleteAttribute} 177 This routine removes the attribute {\tt name} 178 from object {\tt o}. Returns {\tt o} on success or if the 179 attribute does not exist, or returns null 180 and sets the error code to indicate an error. 181 **/ 182 183 Object DXGetAttribute(Object o, char *name); 184 Object DXGetEnumeratedAttribute(Object o, int n, char **name); 185 /** 186 \index{DXGetAttribute}\index{DXGetEnumeratedAttribute} 187 {\tt DXGetAttribute} retrieves the attribute specified by {\tt name} 188 from object {\tt o}. {\tt DXGetEnumeratedAttribute} retrieves the {\tt 189 n}th attribute of object {\tt o}, and returns a pointer its name in 190 {\tt name}. Returns {\tt o} on success, or returns null but does not 191 set the error code if the attribute does not exist. 192 **/ 193 194 Object DXSetFloatAttribute(Object o, char *name, double x); 195 Object DXSetIntegerAttribute(Object o, char *name, int x); 196 Object DXSetStringAttribute(Object o, char *name, char *x); 197 /** 198 \index{DXSetFloatAttribute}\index{DXSetIntegerAttribute}\index{DXSetStringAttribute} 199 These routines provide an easy way to associate a floating point, integer, 200 or string attribute {\tt x} named {\tt name} with object {\tt o}. The 201 float and integer attributes are represented by arrays; the string attribute 202 is represented by a string object. Returns {\tt o} on success, or returns 203 null and sets the error code to indicate an error. 204 **/ 205 206 Object DXGetFloatAttribute(Object o, char *name, float *x); 207 Object DXGetIntegerAttribute(Object o, char *name, int *x); 208 Object DXGetStringAttribute(Object o, char *name, char **x); 209 /** 210 \index{DXGetFloatAttribute}\index{DXGetIntegerAttribute}\index{DXGetStringAttribute} 211 These routines provide an easy way to retrieve a floating point, integer, 212 or string attribute {\tt x} named {\tt name} from object {\tt o}. 213 If the attribute exists, these routines set pointer {\tt x} to the value. 214 Returns {\tt o} on success, or returns null but does not set the error code. 215 **/ 216 217 Object DXCopyAttributes(Object dst, Object src); 218 /** 219 \index{DXCopyAttributes} 220 For each attribute in {\tt src}, that attribute in {\tt dst} is set to 221 the value from {\tt src}, overriding any setting it may have in {\tt 222 dst}. Attributes that are present in {\tt dst} but not present in 223 {\tt src} remain unchanged. Returns {\tt dst} on success, or returns 224 null and sets the error code to indicate an error. 225 **/ 226 227 enum _dxd_copy { 228 COPY_ATTRIBUTES, 229 COPY_HEADER, 230 COPY_STRUCTURE, 231 COPY_DATA 232 }; 233 234 Object DXCopy(Object o, enum _dxd_copy copy); 235 /** 236 \index{DXCopy} 237 A variety of object copying operations are provided, differing in the 238 depth to which they copy the structure of an object. The depth is 239 specified by the {\tt copy} parameter, which may be one of the 240 following (at present, only {\tt COPY\_STRUCTURE} is supported): 241 242 {\tt COPY\_DATA}: Copies the entire data structure, including all headers, 243 attributes, members, components, and arrays (including array data). 244 Note: this is not implemented in the current version of the Data Explorer. 245 \marginpar{Is this true?} 246 247 {\tt COPY\_STRUCTURE}: For {\tt Group}s, this copies the group header and 248 recursively copies all group members. For {\tt Field}s, it copies the field 249 header but {\em does not} copy the components (which are generally arrays); 250 rather if puts references to the components of the given 251 object into the resulting field. 252 253 {\tt COPY\_HEADER}: Copies only the header of the immediate object; {\em does 254 not} recursively copy the attributes, members, components, and so on; rather 255 it puts references to them into the new object. 256 257 {\tt COPY\_ATTRIBUTES}: Creates a new object of the same type as the 258 old, and copies all attributes and type information, but does {\em 259 not} put references to members, components, and so on in the new object. 260 261 Returns the copy, or returns null and sets the error code to indicate an 262 error. 263 **/ 264 265 266 Object DXEndObject(Object o); 267 /** 268 \index{DXEndObject} 269 This routine does any standard processing needed after an object is 270 created. It currently only called DXEndField on all field objects, 271 but preserves shared components if the object is a group of fields 272 which share components like positions or connections. 273 **/ 274 275 276 /* 277 \paragraph{Types.} 278 Several object classes implement a notion of type. For {\tt Array}s, 279 this is the same as the type set when the array was created, and is 280 the same as the information returned by {\tt DXGetArrayInfo}. (See 281 section \ref{arraysec}.) For {\tt Field}s, this is the same as the 282 type of the ``data'' component, if there is a data component. For 283 {\tt Group}s, this is the type set explicitly by {\tt DXSetGroupType()} or 284 implicitly for series groups or composite groups, 285 */ 286 287 typedef enum { 288 TYPE_BYTE, 289 TYPE_UBYTE, 290 TYPE_USHORT, 291 TYPE_UINT, 292 TYPE_SHORT, 293 TYPE_INT, 294 TYPE_HYPER, 295 TYPE_FLOAT, 296 TYPE_DOUBLE, 297 TYPE_STRING 298 } Type; 299 300 typedef enum { 301 CATEGORY_REAL, 302 CATEGORY_COMPLEX, 303 CATEGORY_QUATERNION 304 } Category; 305 306 Object DXGetType(Object o, Type *t, Category *c, int *rank, int *shape); 307 /** 308 \index{DXGetType} 309 If {\tt t} is not null, this routine returns the type of {\tt g} in {\tt *t}. 310 If {\tt c} is not null, it returns the type of {\tt g} in {\tt *c}. 311 If {\tt rank} is not null, it returns the rank of {\tt g} in {\tt *rank}. 312 If {\tt shape} is not null, it returns the shape array of {\tt g} in 313 {\tt *shape}. Returns {\tt o} on if there is a type associated with 314 {\tt o}, or returns null but does not set the error code if there is 315 no type associated with {\tt o}. 316 **/ 317 318 int DXTypeSize(Type t); 319 int DXCategorySize(Category c); 320 /** 321 \index{DXTypeSize}\index{DXCategorySize} 322 {\tt DXTypeSize()} returns the size in bytes of a variable of type {\tt t}. 323 {\tt DXCategorySize()} returns the size multiplier for category {\tt c}. 324 For a variable of type {\tt t} and category {\tt c}, the size in bytes is 325 {\tt DXTypeSize(t) * DXCategorySize(c)}. 326 **/ 327 328 Error DXPrint(Object o, char *options, ...); 329 Error DXPrintV(Object o, char *options, char **components); 330 /** 331 \index{DXPrint}\index{DXPrintV} 332 Prints {\tt o} according to the specified {\tt options}; see the DXPrint 333 module for a description of the options. Prints the components 334 specified by the null-terminated list of string arguments following 335 {\tt options} in the case of {\tt DXPrint()}, or by a null-terminated 336 array of pointers to names of components in the case of {\tt 337 DXPrintV()}. If no components are specified or if {\tt components} is 338 null, all components are printed. Returns {\tt OK} on success, or 339 returns null and sets the error code to indicate an error. 340 **/ 341 342 #endif /* _DXI_OBJECT_H_ */ 343 344 #if defined(__cplusplus) || defined(c_plusplus) 345 #undef private 346 } 347 #endif 348 349