VIA - Volumetric Image Analysis
viaio/Vlib.h
1 /*
2  * $Id: Vlib.h 726 2004-03-08 13:12:45Z lohmann $
3  *
4  * Definitions associated with the Vista library of vision software.
5  */
6 
7 #ifndef V_Vlib_h
8 #define V_Vlib_h 1
9 
10 /*
11  * Copyright 1993, 1994 University of British Columbia
12  *
13  * Permission to use, copy, modify, distribute, and sell this software and its
14  * documentation for any purpose is hereby granted without fee, provided that
15  * the above copyright notice appears in all copies and that both that
16  * copyright notice and this permission notice appear in supporting
17  * documentation. UBC makes no representations about the suitability of this
18  * software for any purpose. It is provided "as is" without express or
19  * implied warranty.
20  *
21  * Author: Arthur Pope, UBC Laboratory for Computational Intelligence
22  */
23 
24 
25 /* For portability: */
26 #include <X11/Xfuncproto.h>
27 
28 /* Get definition of size_t and NULL: */
29 #include <stddef.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 
36 /*
37  * Basic constants.
38  */
39 
40 #ifndef FALSE
41 #define FALSE 0
42 #define TRUE 1
43 #endif
44 
45 
46 /*
47  * Basic types.
48  */
49 
50 /* Numeric types: */
51 /* (These definitions may be platform-specific.) */
52 typedef char VBit; /* 0 or 1 */
53 typedef double VDouble; /* >= 64-bit IEEE floating point */
54 typedef float VFloat; /* >= 32-bit IEEE floating point */
55 
56 /* typedef long VLong; */ /* >= 32-bit signed integer */
57 typedef long VLong; /* !! changed, G.L. 19.9.95 !! */
58 
59 #if __STDC__
60 typedef signed char VSByte; /* integer in [-128,127] */
61 #else
62 typedef char VSByte; /* integer in [-128,127] */
63 #endif
64 typedef short VShort; /* >= 16-bit signed integer */
65 typedef unsigned char VUByte; /* integer in [0,255] */
66 
67 /* Macros for generating constants of particular numeric types: */
68 /* (These definitions may be platform-specific.) */
69 #define VBitConst(c) (c)
70 #define VUByteConst(c) (c)
71 #define VSByteConst(c) (c)
72 #define VShortConst(c) (c)
73 #define VLongConst(c) (c ## l)
74 #if __STDC__
75 #define VFloatConst(c) (c ## f)
76 #define VDoubleConst(c) (c)
77 #else
78 #define VFloatConst(c) ((VFloat) c)
79 #define VDoubleConst(c) ((VDouble) c)
80 #endif
81 
82 /* Miscellaneous types: */
83 /* (These definitions may be platform-specific.) */
84 typedef char VBoolean; /* TRUE or FALSE */
85 #if __STDC__ || defined(__cplusplus) || defined(c_plusplus)
86 typedef void *VPointer; /* generic pointer */
87 typedef const char *VStringConst; /* null-terminated string constant */
88 #else
89 typedef char *VPointer; /* generic pointer */
90 typedef char *VStringConst; /* null-terminated string constant */
91 #endif
92 typedef char *VString; /* null-terminated string */
93 
94 /* What they are promoted to, as arguments, on the various platforms: */
95 /* (These definitions may be platform-specific.) */
96 typedef int VBitPromoted;
97 typedef int VBooleanPromoted;
98 typedef double VDoublePromoted;
99 typedef double VFloatPromoted;
100 typedef long VLongPromoted;
101 typedef int VSBytePromoted;
102 typedef int VShortPromoted;
103 typedef unsigned int VUBytePromoted;
104 
105 /* Standard object types: */
106 typedef struct V_EdgesRec *VEdges; /* edge set */
107 typedef struct V_ImageRec *VImage; /* image */
108 typedef struct V_VolumesRec *Volumes; /* volumes */
109 
110 /* Codes for referring to representations: */
111 typedef enum {
112  VUnknownRepn,
113 
114  /* Integer numbers: */
115  VBitRepn, /* 1-bit integer, [0, 1] */
116  VUByteRepn, /* 8-bit integer, [0, 255] */
117  VSByteRepn, /* 8-bit integer, [-128, 127] */
118  VShortRepn, /* 16-bit integer, [-32768, 32767] */
119  VLongRepn, /* 32-bit integer, [-2**31, 2**31-1] */
120 
121  /* Floating point numbers: */
122  VFloatRepn, /* 32-bit IEEE floating point */
123  VDoubleRepn, /* 64-bit IEEE floating point */
124 
125  /* Miscellaneous representations: */
126  VAttrListRepn, /* attribute list */
127  VBooleanRepn, /* TRUE or FALSE */
128  VBundleRepn, /* object of named type */
129  VListRepn, /* list of opaque objects */
130  VPointerRepn, /* pointer to opaque object */
131  VStringRepn, /* null-terminated string */
132 
133  /* Standard object types: */
134  VEdgesRepn, /* edge set */
135  VImageRepn, /* image */
136 
137  /* New object types */
138  VGraphRepn, /* graph */
139  VolumesRepn, /* volumes */
140  VNRepnKinds /* number of predefined types */
141 } VRepnKind;
142 
143 
144 /*
145  * Attribute list representation.
146  */
147 
148 /* Each attribute name/value pair is represented by: */
149 typedef struct V_AttrRec {
150  struct V_AttrRec *next; /* next in list */
151  struct V_AttrRec *prev; /* previous in list */
152  VRepnKind repn; /* rep'n of attribute value */
153  VPointer value; /* pointer to attribute value */
154  char name[1]; /* beginning of name string */
155 } VAttrRec;
156 
157 /* A list of attributes is represented by a header node: */
158 typedef VAttrRec *VAttrList;
159 
160 /* Macros for testing an attribute list: */
161 #define VAttrListEmpty(l) ((l) == NULL || (l)->next == NULL)
162 
163 /* Position within a list of attributes: */
164 typedef struct {
165  VAttrList list; /* the list */
166  struct V_AttrRec *ptr; /* position within the list */
167 } VAttrListPosn;
168 
169 /* Macros for moving up and down an attribute list: */
170 #define VFirstAttr(l,p) ((void) ((p)->list = (l), (p)->ptr = (l)->next))
171 #define VLastAttr(l,p) ((void) ((p)->list = (l), (p)->ptr = (l)->prev))
172 #define VAttrExists(p) ((p)->ptr != NULL)
173 #define VNextAttr(p) ((void) ((p)->ptr = (p)->ptr ? (p)->ptr->next : NULL))
174 #define VPrevAttr(p) ((void) ((p)->ptr = (p)->ptr ? (p)->ptr->prev : NULL))
175 
176 /* Macros for accessing the attribute at a particular position in an list: */
177 #define VGetAttrName(p) ((p)->ptr->name)
178 #define VGetAttrRepn(p) ((p)->ptr->repn)
179 
180 /* Result of trying to retrieve an attribute's value: */
181 typedef enum {
182  VAttrFound, /* successfully retrieved value */
183  VAttrMissing, /* didn't find attribute */
184  VAttrBadValue /* incompatible value */
185 } VGetAttrResult;
186 
187 /* Names of generic attributes: */
188 #define VCommentAttr "comment"
189 #define VDataAttr "data"
190 #define VHistoryAttr "history"
191 #define VLengthAttr "length"
192 #define VNameAttr "name"
193 #define VNColumnsAttr "ncolumns"
194 #define VNRowsAttr "nrows"
195 #define VRepnAttr "repn"
196 
197 /* An object whose type is named but not registered: */
198 typedef struct {
199  VAttrList list; /* object's attribute list value */
200  size_t length; /* length of binary data */
201  VPointer data; /* pointer to binary data */
202  char type_name[1]; /* beginning of object's type's name */
203 } VBundleRec, *VBundle;
204 
205 
206 /*
207  * Object type registry.
208  */
209 
210 /* Type of procedure for copying object's value: */
211 typedef VPointer VCopyMethod (
212 #if NeedFunctionPrototypes
213  VPointer /* value */
214 #endif
215 );
216 
217 /* Type of procedure for destroying object's value: */
218 typedef void VDestroyMethod (
219 #if NeedFunctionPrototypes
220  VPointer /* value */
221 #endif
222 );
223 
224 /* Type of procedure for decoding object's binary data: */
225 typedef VPointer VDecodeMethod (
226 #if NeedFunctionPrototypes
227  VStringConst /* name */,
228  VBundle /* bundle */
229 #endif
230 );
231 
232 /* Type of procedure for encoding object's attr list: */
233 typedef VAttrList VEncodeAttrMethod (
234 #if NeedFunctionPrototypes
235  VPointer /* value */,
236  size_t * /* length */
237 #endif
238 );
239 
240 /* Type of procedure for encoding object's binary data: */
241 typedef VPointer VEncodeDataMethod (
242 #if NeedFunctionPrototypes
243  VPointer /* value */,
244  VAttrList /* list */,
245  size_t /* length */,
246  VBoolean * /* free_it */
247 #endif
248 );
249 
250 /* Set of methods supporting an object type: */
251 typedef struct {
252  VCopyMethod *copy;
253  VDestroyMethod *destroy;
254  VDecodeMethod *decode;
255  VEncodeAttrMethod *encode_attr;
256  VEncodeDataMethod *encode_data;
257 } VTypeMethods;
258 
259 /* Information about a representation: */
260 typedef struct {
261  VStringConst name; /* name string */
262  size_t size; /* size, in bytes */
263  int precision; /* precision, in bits */
264  VDouble min_value; /* min and max representable values */
265  VDouble max_value;
266  VTypeMethods *methods; /* associated methods */
267 } VRepnInfoRec;
268 
269 /* Table indexed by representation: */
270 extern VRepnInfoRec *VRepnInfo;
271 
272 /* Macros for accessing information about representations: */
273 #define VRepnSize(repn) (VRepnInfo[repn].size)
274 #define VRepnPrecision(repn) (VRepnInfo[repn].precision)
275 #define VRepnName(repn) (VRepnInfo[repn].name)
276 #define VRepnMinValue(repn) (VRepnInfo[repn].min_value)
277 #define VRepnMaxValue(repn) (VRepnInfo[repn].max_value)
278 #define VRepnMethods(repn) (VRepnInfo[repn].methods)
279 
280 #define VIsIntegerRepn(repn) ((repn) >= VBitRepn && (repn) <= VLongRepn)
281 #define VIsFloatPtRepn(repn) ((repn) == VFloatRepn || (repn) == VDoubleRepn)
282 
283 
284 /*
285  * Dictionary describing keyword/value mapping.
286  */
287 
288 /* Dictionary entry: */
289 typedef struct {
290 
291  /* The following are initialized by the dictionary provider: */
292  VStringConst keyword; /* keyword string */
293  VLong ivalue; /* value, if an integer */
294  VStringConst svalue; /* value, if a string */
295 
296  /* The following are used only by code in VLookupDictValue: */
297  VBoolean icached; /* whether integer value cached */
298  VBoolean fcached; /* whether float value cached */
299  VDouble fvalue; /* cached floating-point value */
300 } VDictEntry;
301 
302 /* Dictionaries of keywords for attribute values: */
303 extern VDictEntry VBooleanDict[]; /* boolean values */
304 extern VDictEntry VNumericRepnDict[]; /* numeric representation kinds */
305 
306 
307 /*
308  * Other definitions.
309  */
310 
311 /* Order in which to pack bits or bytes: */
312 typedef enum { VLsbFirst, VMsbFirst } VPackOrder;
313 
314 
315 /*
316  * Declarations of library routines.
317  */
318 
319 /* From Alloc.c: */
320 
321 extern VPointer VCalloc (
322 #if NeedFunctionPrototypes
323  size_t /* n */,
324  size_t /* size */
325 #endif
326 );
327 
328 extern void VFree (
329 #if NeedFunctionPrototypes
330  VPointer /* p */
331 #endif
332 );
333 
334 extern VPointer VMalloc (
335 #if NeedFunctionPrototypes
336  size_t /* size */
337 #endif
338 );
339 
340 extern VPointer VRealloc (
341 #if NeedFunctionPrototypes
342  VPointer /* p */,
343  size_t /* size */
344 #endif
345 );
346 
347 /* From Attr.c: */
348 
349 extern void VAppendAttr (
350 #if NeedVarargsPrototypes
351  VAttrList /* list */,
352  VStringConst /* name */,
353  VDictEntry * /* dict */,
354  VRepnKind /* repn */,
355  ... /* value */
356 #endif
357 );
358 
359 extern VAttrList VCopyAttrList (
360 #if NeedFunctionPrototypes
361  VAttrList /* list */
362 #endif
363 );
364 
365 extern VAttrList VCreateAttrList (
366 #if NeedFunctionPrototypes
367  void
368 #endif
369 );
370 
371 extern VBundle VCreateBundle (
372 #if NeedFunctionPrototypes
373  VStringConst /* type_name */,
374  VAttrList /* list */,
375  size_t /* length */,
376  VPointer /* data */
377 #endif
378 );
379 
380 extern VBoolean VDecodeAttrValue (
381 #if NeedFunctionPrototypes
382  VStringConst /* str */,
383  VDictEntry * /* dict */,
384  VRepnKind /* repn */,
385  VPointer /* value */
386 #endif
387 );
388 
389 extern void VDeleteAttr (
390 #if NeedFunctionPrototypes
391  VAttrListPosn * /* posn */
392 #endif
393 );
394 
395 extern void VDestroyAttrList (
396 #if NeedFunctionPrototypes
397  VAttrList /* list */
398 #endif
399 );
400 
401 extern void VDestroyBundle (
402 #if NeedFunctionPrototypes
403  VBundle /* bundle */
404 #endif
405 );
406 
407 extern VStringConst VEncodeAttrValue (
408 #if NeedVarargsPrototypes
409  VDictEntry * /* dict */,
410  VRepnKind /* repn */,
411  ... /* value */
412 #endif
413 );
414 
415 extern VBoolean VExtractAttr (
416 #if NeedFunctionPrototypes
417  VAttrList /* list */,
418  VStringConst /* name */,
419  VDictEntry * /* dict */,
420  VRepnKind /* repn */,
421  VPointer /* value */,
422  VBooleanPromoted /* required */
423 #endif
424 );
425 
426 extern VGetAttrResult VGetAttr (
427 #if NeedFunctionPrototypes
428  VAttrList /* list */,
429  VStringConst /* name */,
430  VDictEntry * /* dict */,
431  VRepnKind /* repn */,
432  VPointer /* value */
433 #endif
434 );
435 
436 extern VBoolean VGetAttrValue (
437 #if NeedFunctionPrototypes
438  VAttrListPosn * /* posn */,
439  VDictEntry * /* dict */,
440  VRepnKind /* repn */,
441  VPointer /* value */
442 #endif
443 );
444 
445 extern void VInsertAttr (
446 #if NeedVarargsPrototypes
447  VAttrListPosn * /* posn */,
448  VBooleanPromoted /* after */,
449  VStringConst /* name */,
450  VDictEntry * /* dict */,
451  VRepnKind /* repn */,
452  ... /* value */
453 #endif
454 );
455 
456 extern VBoolean VLookupAttr (
457 #if NeedFunctionPrototypes
458  VAttrList /* list */,
459  VStringConst /* name */,
460  VAttrListPosn * /* posn */
461 #endif
462 );
463 
464 extern void VPrependAttr (
465 #if NeedVarargsPrototypes
466  VAttrList /* list */,
467  VStringConst /* name */,
468  VDictEntry * /* dict */,
469  VRepnKind /* repn */,
470  ... /* value */
471 #endif
472 );
473 
474 extern void VSetAttr (
475 #if NeedVarargsPrototypes
476  VAttrList /* list */,
477  VStringConst /* name */,
478  VDictEntry * /* dict */,
479  VRepnKind /* repn */,
480  ... /* value */
481 #endif
482 );
483 
484 extern void VSetAttrValue (
485 #if NeedVarargsPrototypes
486  VAttrListPosn * /* posn */,
487  VDictEntry * /* dict */,
488  VRepnKind /* repn */,
489  ... /* value */
490 #endif
491 );
492 
493 /* From Dictionary.c: */
494 
495 extern VDictEntry *VLookupDictKeyword (
496 #if NeedFunctionPrototypes
497  VDictEntry * /* dict */,
498  VStringConst /* keyword */
499 #endif
500 );
501 
502 extern VDictEntry *VLookupDictValue (
503 #if NeedVarargsPrototypes
504  VDictEntry * /* dict */,
505  VRepnKind /* repn */,
506  ... /* value */
507 #endif
508 );
509 
510 /* From Error.c: */
511 
512 typedef void VErrorHandler (
513 #if NeedFunctionPrototypes
514  VStringConst /* message */
515 #endif
516 );
517 
518 typedef void VWarningHandler (
519 #if NeedFunctionPrototypes
520  VStringConst /* message */
521 #endif
522 );
523 
524 extern void VSetErrorHandler (
525 #if NeedFunctionPrototypes
526  VErrorHandler * /* fnc */
527 #endif
528 );
529 
530 extern void VSetWarningHandler (
531 #if NeedFunctionPrototypes
532  VWarningHandler * /* fnc */
533 #endif
534 );
535 
536 extern void VSetProgramName (
537 #if NeedFunctionPrototypes
538  VStringConst /* name */
539 #endif
540 );
541 
542 extern void VError (
543 #if NeedVarargsPrototypes
544  VStringConst /* format */,
545  ... /* args */
546 #endif
547 );
548 
549 extern void VWarning (
550 #if NeedVarargsPrototypes
551  VStringConst /* format */,
552  ... /* args */
553 #endif
554 );
555 
556 extern void VSystemError (
557 #if NeedVarargsPrototypes
558  VStringConst /* format */,
559  ... /* args */
560 #endif
561 );
562 
563 extern void VSystemWarning (
564 #if NeedVarargsPrototypes
565  VStringConst /* format */,
566  ... /* args */
567 #endif
568 );
569 
570 extern void VDefaultError (
571 #if NeedFunctionPrototypes
572  VStringConst /* message */
573 #endif
574 );
575 
576 extern void VDefaultWarning (
577 #if NeedFunctionPrototypes
578  VStringConst /* message */
579 #endif
580 );
581 
582 /* From PackData.c: */
583 
584 VBoolean VPackData (
585 #if NeedFunctionPrototypes
586  VRepnKind /* repn */,
587  size_t /* nels */,
588  VPointer /* unpacked */,
589  VPackOrder /* packed_order */,
590  size_t * /* length */,
591  VPointer * /* packed */,
592  VBoolean * /* alloced */
593 #endif
594 );
595 
596 VBoolean VUnpackData (
597 #if NeedFunctionPrototypes
598  VRepnKind /* repn */,
599  size_t /* nels */,
600  VPointer /* packed */,
601  VPackOrder /* packed_order */,
602  size_t * /* length */,
603  VPointer * /* unpacked */,
604  VBoolean * /* alloced */
605 #endif
606 );
607 
608 void VPackBits (
609 #if NeedFunctionPrototypes
610  size_t /* nels */,
611  VPackOrder /* packed_order */,
612  VBit * /* unpacked */,
613  char * /* packed */
614 #endif
615 );
616 
617 void VUnpackBits (
618 #if NeedFunctionPrototypes
619  size_t /* nels */,
620  VPackOrder /* packed_order */,
621  char * /* packed */,
622  VBit * /* unpacked */
623 #endif
624 );
625 
626 /* From Type.c: */
627 
628 VRepnKind VRegisterType (
629 #if NeedFunctionPrototypes
630  VStringConst /* name */,
631  VTypeMethods * /* methods */
632 #endif
633 );
634 
635 VRepnKind VLookupType (
636 #if NeedFunctionPrototypes
637  VStringConst /* name */
638 #endif
639 );
640 
641 #ifdef __cplusplus
642 }
643 #endif
644 
645 #endif /* V_Vlib_h */