VIA - Volumetric Image Analysis
Vlib.h
00001 /*
00002  *  $Id: Vlib.h 726 2004-03-08 13:12:45Z lohmann $
00003  *
00004  *  Definitions associated with the Vista library of vision software.
00005  */
00006 
00007 #ifndef V_Vlib_h
00008 #define V_Vlib_h 1
00009 
00010 /*
00011  *  Copyright 1993, 1994 University of British Columbia
00012  *
00013  *  Permission to use, copy, modify, distribute, and sell this software and its
00014  *  documentation for any purpose is hereby granted without fee, provided that
00015  *  the above copyright notice appears in all copies and that both that
00016  *  copyright notice and this permission notice appear in supporting
00017  *  documentation. UBC makes no representations about the suitability of this
00018  *  software for any purpose. It is provided "as is" without express or
00019  *  implied warranty.
00020  *
00021  *  Author: Arthur Pope, UBC Laboratory for Computational Intelligence
00022  */
00023 
00024 
00025 /* For portability: */
00026 #include <X11/Xfuncproto.h>
00027 
00028 /* Get definition of size_t and NULL: */
00029 #include <stddef.h>
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 
00036 /*
00037  *  Basic constants.
00038  */
00039 
00040 #ifndef FALSE
00041 #define FALSE 0
00042 #define TRUE 1
00043 #endif
00044 
00045 
00046 /*
00047  *  Basic types.
00048  */
00049 
00050 /* Numeric types: */
00051 /* (These definitions may be platform-specific.) */
00052 typedef char VBit;                      /* 0 or 1 */
00053 typedef double VDouble;                 /* >= 64-bit IEEE floating point */
00054 typedef float VFloat;                   /* >= 32-bit IEEE floating point */
00055 
00056 /* typedef long VLong;  */              /* >= 32-bit signed integer */
00057 typedef long VLong;                     /* !! changed, G.L. 19.9.95 !! */
00058 
00059 #if __STDC__
00060 typedef signed char VSByte;             /* integer in [-128,127] */
00061 #else
00062 typedef char VSByte;                    /* integer in [-128,127] */
00063 #endif
00064 typedef short VShort;                   /* >= 16-bit signed integer */
00065 typedef unsigned char VUByte;           /* integer in [0,255] */
00066 
00067 /* Macros for generating constants of particular numeric types: */
00068 /* (These definitions may be platform-specific.) */
00069 #define VBitConst(c)    (c)
00070 #define VUByteConst(c)  (c)
00071 #define VSByteConst(c)  (c)
00072 #define VShortConst(c)  (c)
00073 #define VLongConst(c)   (c ## l)
00074 #if __STDC__
00075 #define VFloatConst(c)  (c ## f)
00076 #define VDoubleConst(c) (c)
00077 #else
00078 #define VFloatConst(c)  ((VFloat) c)
00079 #define VDoubleConst(c) ((VDouble) c)
00080 #endif
00081 
00082 /* Miscellaneous types: */
00083 /* (These definitions may be platform-specific.) */
00084 typedef char VBoolean;                  /* TRUE or FALSE */
00085 #if __STDC__ || defined(__cplusplus) || defined(c_plusplus)
00086 typedef void *VPointer;                 /* generic pointer */
00087 typedef const char *VStringConst;       /* null-terminated string constant */
00088 #else
00089 typedef char *VPointer;                 /* generic pointer */
00090 typedef char *VStringConst;             /* null-terminated string constant */
00091 #endif
00092 typedef char *VString;                  /* null-terminated string */
00093 
00094 /* What they are promoted to, as arguments, on the various platforms: */
00095 /* (These definitions may be platform-specific.) */
00096 typedef int VBitPromoted;
00097 typedef int VBooleanPromoted;
00098 typedef double VDoublePromoted;
00099 typedef double VFloatPromoted;
00100 typedef long VLongPromoted;
00101 typedef int VSBytePromoted;
00102 typedef int VShortPromoted;
00103 typedef unsigned int VUBytePromoted;
00104 
00105 /* Standard object types: */
00106 typedef struct V_EdgesRec *VEdges;      /* edge set */
00107 typedef struct V_ImageRec *VImage;      /* image    */
00108 typedef struct V_VolumesRec *Volumes;   /* volumes  */
00109 
00110 /* Codes for referring to representations: */
00111 typedef enum {
00112     VUnknownRepn,
00113 
00114     /* Integer numbers: */
00115     VBitRepn,                           /* 1-bit integer, [0, 1] */
00116     VUByteRepn,                         /* 8-bit integer, [0, 255] */
00117     VSByteRepn,                         /* 8-bit integer, [-128, 127] */
00118     VShortRepn,                         /* 16-bit integer, [-32768, 32767] */
00119     VLongRepn,                          /* 32-bit integer, [-2**31, 2**31-1] */
00120 
00121     /* Floating point numbers: */
00122     VFloatRepn,                         /* 32-bit IEEE floating point */
00123     VDoubleRepn,                        /* 64-bit IEEE floating point */
00124 
00125     /* Miscellaneous representations: */
00126     VAttrListRepn,                      /* attribute list */
00127     VBooleanRepn,                       /* TRUE or FALSE */
00128     VBundleRepn,                        /* object of named type */
00129     VListRepn,                          /* list of opaque objects */
00130     VPointerRepn,                       /* pointer to opaque object */
00131     VStringRepn,                        /* null-terminated string */
00132 
00133     /* Standard object types: */
00134     VEdgesRepn,                         /* edge set */
00135     VImageRepn,                         /* image */
00136 
00137     /* New object types */
00138     VGraphRepn,                         /* graph */
00139     VolumesRepn,                        /* volumes */
00140     VNRepnKinds                         /* number of predefined types */
00141 } VRepnKind;
00142 
00143 
00144 /*
00145  *  Attribute list representation.
00146  */
00147 
00148 /* Each attribute name/value pair is represented by: */
00149 typedef struct V_AttrRec {
00150     struct V_AttrRec *next;             /* next in list */
00151     struct V_AttrRec *prev;             /* previous in list */
00152     VRepnKind repn;                     /* rep'n of attribute value */
00153     VPointer value;                     /* pointer to attribute value */
00154     char name[1];                       /* beginning of name string */
00155 } VAttrRec;
00156 
00157 /* A list of attributes is represented by a header node: */
00158 typedef VAttrRec *VAttrList;
00159 
00160 /* Macros for testing an attribute list: */
00161 #define VAttrListEmpty(l) ((l) == NULL || (l)->next == NULL)
00162 
00163 /* Position within a list of attributes: */
00164 typedef struct {
00165     VAttrList list;                     /* the list */
00166     struct V_AttrRec *ptr;              /* position within the list */
00167 } VAttrListPosn;
00168 
00169 /* Macros for moving up and down an attribute list: */
00170 #define VFirstAttr(l,p) ((void) ((p)->list = (l), (p)->ptr = (l)->next))
00171 #define VLastAttr(l,p)  ((void) ((p)->list = (l), (p)->ptr = (l)->prev))
00172 #define VAttrExists(p)  ((p)->ptr != NULL)
00173 #define VNextAttr(p)    ((void) ((p)->ptr = (p)->ptr ? (p)->ptr->next : NULL))
00174 #define VPrevAttr(p)    ((void) ((p)->ptr = (p)->ptr ? (p)->ptr->prev : NULL))
00175 
00176 /* Macros for accessing the attribute at a particular position in an list: */
00177 #define VGetAttrName(p) ((p)->ptr->name)
00178 #define VGetAttrRepn(p) ((p)->ptr->repn)
00179 
00180 /* Result of trying to retrieve an attribute's value: */
00181 typedef enum {
00182     VAttrFound,                         /* successfully retrieved value */
00183     VAttrMissing,                       /* didn't find attribute */
00184     VAttrBadValue                       /* incompatible value */
00185 } VGetAttrResult;
00186 
00187 /* Names of generic attributes: */
00188 #define VCommentAttr    "comment"
00189 #define VDataAttr       "data"
00190 #define VHistoryAttr    "history"
00191 #define VLengthAttr     "length"
00192 #define VNameAttr       "name"
00193 #define VNColumnsAttr   "ncolumns"
00194 #define VNRowsAttr      "nrows"
00195 #define VRepnAttr       "repn"
00196 
00197 /* An object whose type is named but not registered: */
00198 typedef struct {
00199     VAttrList list;                     /* object's attribute list value */
00200     size_t length;                      /* length of binary data */
00201     VPointer data;                      /* pointer to binary data */
00202     char type_name[1];                  /* beginning of object's type's name */
00203 } VBundleRec, *VBundle;
00204 
00205 
00206 /*
00207  *  Object type registry.
00208  */
00209 
00210 /* Type of procedure for copying object's value: */
00211 typedef VPointer VCopyMethod (
00212 #if NeedFunctionPrototypes
00213     VPointer            /* value */
00214 #endif
00215 );
00216 
00217 /* Type of procedure for destroying object's value: */
00218 typedef void VDestroyMethod (
00219 #if NeedFunctionPrototypes
00220     VPointer            /* value */
00221 #endif
00222 );
00223 
00224 /* Type of procedure for decoding object's binary data: */
00225 typedef VPointer VDecodeMethod (
00226 #if NeedFunctionPrototypes
00227     VStringConst        /* name */,
00228     VBundle             /* bundle */
00229 #endif
00230 );
00231 
00232 /* Type of procedure for encoding object's attr list: */
00233 typedef VAttrList VEncodeAttrMethod (
00234 #if NeedFunctionPrototypes
00235     VPointer            /* value */,
00236     size_t *            /* length */
00237 #endif
00238 );
00239 
00240 /* Type of procedure for encoding object's binary data: */
00241 typedef VPointer VEncodeDataMethod (
00242 #if NeedFunctionPrototypes
00243     VPointer            /* value */,
00244     VAttrList           /* list */,
00245     size_t              /* length */,
00246     VBoolean *          /* free_it */
00247 #endif
00248 );
00249 
00250 /* Set of methods supporting an object type: */
00251 typedef struct {
00252     VCopyMethod *copy;
00253     VDestroyMethod *destroy;
00254     VDecodeMethod *decode;
00255     VEncodeAttrMethod *encode_attr;
00256     VEncodeDataMethod *encode_data;
00257 } VTypeMethods;
00258 
00259 /* Information about a representation: */
00260 typedef struct {
00261     VStringConst name;                  /* name string */
00262     size_t size;                        /* size, in bytes */
00263     int precision;                      /* precision, in bits */
00264     VDouble min_value;                  /* min and max representable values */
00265     VDouble max_value;
00266     VTypeMethods *methods;              /* associated methods */
00267 } VRepnInfoRec;
00268 
00269 /* Table indexed by representation: */
00270 extern VRepnInfoRec *VRepnInfo;
00271 
00272 /* Macros for accessing information about representations: */
00273 #define VRepnSize(repn)         (VRepnInfo[repn].size)
00274 #define VRepnPrecision(repn)    (VRepnInfo[repn].precision)
00275 #define VRepnName(repn)         (VRepnInfo[repn].name)
00276 #define VRepnMinValue(repn)     (VRepnInfo[repn].min_value)
00277 #define VRepnMaxValue(repn)     (VRepnInfo[repn].max_value)
00278 #define VRepnMethods(repn)      (VRepnInfo[repn].methods)
00279 
00280 #define VIsIntegerRepn(repn)    ((repn) >= VBitRepn && (repn) <= VLongRepn)
00281 #define VIsFloatPtRepn(repn)    ((repn) == VFloatRepn || (repn) == VDoubleRepn)
00282 
00283 
00284 /*
00285  *  Dictionary describing keyword/value mapping.
00286  */
00287 
00288 /* Dictionary entry: */
00289 typedef struct {
00290 
00291     /* The following are initialized by the dictionary provider: */
00292     VStringConst keyword;               /* keyword string */
00293     VLong ivalue;                       /* value, if an integer */
00294     VStringConst svalue;                /* value, if a string */
00295 
00296     /* The following are used only by code in VLookupDictValue: */
00297     VBoolean icached;                   /* whether integer value cached */
00298     VBoolean fcached;                   /* whether float value cached */
00299     VDouble fvalue;                     /* cached floating-point value */
00300 } VDictEntry;
00301 
00302 /* Dictionaries of keywords for attribute values: */
00303 extern VDictEntry VBooleanDict[];       /* boolean values */
00304 extern VDictEntry VNumericRepnDict[];   /* numeric representation kinds */
00305 
00306 
00307 /*
00308  *  Other definitions.
00309  */
00310 
00311 /* Order in which to pack bits or bytes: */
00312 typedef enum { VLsbFirst, VMsbFirst } VPackOrder;
00313 
00314 
00315 /*
00316  *  Declarations of library routines.
00317  */
00318 
00319 /* From Alloc.c: */
00320 
00321 extern VPointer VCalloc (
00322 #if NeedFunctionPrototypes
00323     size_t              /* n */,
00324     size_t              /* size */
00325 #endif
00326 );
00327 
00328 extern void VFree (
00329 #if NeedFunctionPrototypes
00330     VPointer            /* p */
00331 #endif
00332 );
00333 
00334 extern VPointer VMalloc (
00335 #if NeedFunctionPrototypes
00336     size_t              /* size */
00337 #endif
00338 );
00339 
00340 extern VPointer VRealloc (
00341 #if NeedFunctionPrototypes
00342     VPointer            /* p */,
00343     size_t              /* size */
00344 #endif
00345 );
00346 
00347 /* From Attr.c: */
00348 
00349 extern void VAppendAttr (
00350 #if NeedVarargsPrototypes
00351     VAttrList           /* list */,
00352     VStringConst        /* name */,
00353     VDictEntry *        /* dict */,
00354     VRepnKind           /* repn */,
00355     ...                 /* value */
00356 #endif
00357 );
00358 
00359 extern VAttrList VCopyAttrList (
00360 #if NeedFunctionPrototypes
00361     VAttrList           /* list */
00362 #endif
00363 );
00364 
00365 extern VAttrList VCreateAttrList (
00366 #if NeedFunctionPrototypes
00367     void
00368 #endif
00369 );
00370 
00371 extern VBundle VCreateBundle (
00372 #if NeedFunctionPrototypes
00373     VStringConst        /* type_name */,
00374     VAttrList           /* list */,
00375     size_t              /* length */,
00376     VPointer            /* data */
00377 #endif
00378 );
00379 
00380 extern VBoolean VDecodeAttrValue (
00381 #if NeedFunctionPrototypes
00382     VStringConst        /* str */,
00383     VDictEntry *        /* dict */,
00384     VRepnKind           /* repn */,
00385     VPointer            /* value */
00386 #endif
00387 );
00388 
00389 extern void VDeleteAttr (
00390 #if NeedFunctionPrototypes
00391     VAttrListPosn *     /* posn */
00392 #endif
00393 );
00394 
00395 extern void VDestroyAttrList (
00396 #if NeedFunctionPrototypes
00397     VAttrList           /* list */
00398 #endif
00399 );
00400 
00401 extern void VDestroyBundle (
00402 #if NeedFunctionPrototypes
00403     VBundle             /* bundle */
00404 #endif
00405 );
00406 
00407 extern VStringConst VEncodeAttrValue (
00408 #if NeedVarargsPrototypes
00409     VDictEntry *        /* dict */,
00410     VRepnKind           /* repn */,
00411     ...                 /* value */
00412 #endif
00413 );
00414 
00415 extern VBoolean VExtractAttr (
00416 #if NeedFunctionPrototypes
00417     VAttrList           /* list */,
00418     VStringConst        /* name */,
00419     VDictEntry *        /* dict */,
00420     VRepnKind           /* repn */,
00421     VPointer            /* value */,
00422     VBooleanPromoted    /* required */
00423 #endif
00424 );
00425 
00426 extern VGetAttrResult VGetAttr (
00427 #if NeedFunctionPrototypes
00428     VAttrList           /* list */,
00429     VStringConst        /* name */,
00430     VDictEntry *        /* dict */,
00431     VRepnKind           /* repn */,
00432     VPointer            /* value */
00433 #endif
00434 );
00435 
00436 extern VBoolean VGetAttrValue (
00437 #if NeedFunctionPrototypes
00438     VAttrListPosn *     /* posn */,
00439     VDictEntry *        /* dict */,
00440     VRepnKind           /* repn */,
00441     VPointer            /* value */
00442 #endif
00443 );
00444 
00445 extern void VInsertAttr (
00446 #if NeedVarargsPrototypes
00447     VAttrListPosn *     /* posn */,
00448     VBooleanPromoted    /* after */,
00449     VStringConst        /* name */,
00450     VDictEntry *        /* dict */,
00451     VRepnKind           /* repn */,
00452     ...                 /* value */
00453 #endif
00454 );
00455 
00456 extern VBoolean VLookupAttr (
00457 #if NeedFunctionPrototypes
00458     VAttrList           /* list */,
00459     VStringConst        /* name */,
00460     VAttrListPosn *     /* posn */
00461 #endif
00462 );
00463 
00464 extern void VPrependAttr (
00465 #if NeedVarargsPrototypes
00466     VAttrList           /* list */,
00467     VStringConst        /* name */,
00468     VDictEntry *        /* dict */,
00469     VRepnKind           /* repn */,
00470     ...                 /* value */
00471 #endif
00472 );
00473 
00474 extern void VSetAttr (
00475 #if NeedVarargsPrototypes
00476     VAttrList           /* list */,
00477     VStringConst        /* name */,
00478     VDictEntry *        /* dict */,
00479     VRepnKind           /* repn */,
00480     ...                 /* value */
00481 #endif
00482 );
00483 
00484 extern void VSetAttrValue (
00485 #if NeedVarargsPrototypes
00486     VAttrListPosn *     /* posn */,
00487     VDictEntry *        /* dict */,
00488     VRepnKind           /* repn */,
00489     ...                 /* value */
00490 #endif
00491 );
00492 
00493 /* From Dictionary.c: */
00494 
00495 extern VDictEntry *VLookupDictKeyword (
00496 #if NeedFunctionPrototypes
00497     VDictEntry *        /* dict */,
00498     VStringConst        /* keyword */
00499 #endif
00500 );
00501 
00502 extern VDictEntry *VLookupDictValue (
00503 #if NeedVarargsPrototypes
00504     VDictEntry *        /* dict */,
00505     VRepnKind           /* repn */,
00506     ...                 /* value */
00507 #endif
00508 );
00509 
00510 /* From Error.c: */
00511 
00512 typedef void VErrorHandler (
00513 #if NeedFunctionPrototypes
00514     VStringConst        /* message */
00515 #endif
00516 );
00517 
00518 typedef void VWarningHandler (
00519 #if NeedFunctionPrototypes
00520     VStringConst        /* message */
00521 #endif
00522 );
00523 
00524 extern void VSetErrorHandler (
00525 #if NeedFunctionPrototypes
00526     VErrorHandler *     /* fnc */
00527 #endif
00528 );
00529 
00530 extern void VSetWarningHandler (
00531 #if NeedFunctionPrototypes
00532     VWarningHandler *   /* fnc */
00533 #endif
00534 );
00535 
00536 extern void VSetProgramName (
00537 #if NeedFunctionPrototypes
00538     VStringConst        /* name */
00539 #endif
00540 );
00541 
00542 extern void VError (
00543 #if NeedVarargsPrototypes
00544     VStringConst        /* format */,
00545     ...                 /* args */
00546 #endif
00547 );
00548 
00549 extern void VWarning (
00550 #if NeedVarargsPrototypes
00551     VStringConst        /* format */,
00552     ...                 /* args */
00553 #endif
00554 );
00555 
00556 extern void VSystemError (
00557 #if NeedVarargsPrototypes
00558     VStringConst        /* format */,
00559     ...                 /* args */
00560 #endif
00561 );
00562 
00563 extern void VSystemWarning (
00564 #if NeedVarargsPrototypes
00565     VStringConst        /* format */,
00566     ...                 /* args */
00567 #endif
00568 );
00569 
00570 extern void VDefaultError (
00571 #if NeedFunctionPrototypes
00572     VStringConst        /* message */
00573 #endif
00574 );
00575 
00576 extern void VDefaultWarning (
00577 #if NeedFunctionPrototypes
00578     VStringConst        /* message */
00579 #endif
00580 );
00581 
00582 /* From PackData.c: */
00583 
00584 VBoolean VPackData (
00585 #if NeedFunctionPrototypes
00586     VRepnKind           /* repn */,
00587     size_t              /* nels */,
00588     VPointer            /* unpacked */,
00589     VPackOrder          /* packed_order */,
00590     size_t *            /* length */,
00591     VPointer *          /* packed */,
00592     VBoolean *          /* alloced */
00593 #endif
00594 );
00595 
00596 VBoolean VUnpackData (
00597 #if NeedFunctionPrototypes
00598     VRepnKind           /* repn */,
00599     size_t              /* nels */,
00600     VPointer            /* packed */,
00601     VPackOrder          /* packed_order */,
00602     size_t *            /* length */,
00603     VPointer *          /* unpacked */,
00604     VBoolean *          /* alloced */
00605 #endif
00606 );
00607 
00608 void VPackBits (
00609 #if NeedFunctionPrototypes
00610     size_t              /* nels */,
00611     VPackOrder          /* packed_order */,
00612     VBit *              /* unpacked */,
00613     char *              /* packed */
00614 #endif
00615 );
00616 
00617 void VUnpackBits (
00618 #if NeedFunctionPrototypes
00619     size_t              /* nels */,
00620     VPackOrder          /* packed_order */,
00621     char *              /* packed */,
00622     VBit *              /* unpacked */
00623 #endif
00624 );
00625 
00626 /* From Type.c: */
00627 
00628 VRepnKind VRegisterType (
00629 #if NeedFunctionPrototypes
00630     VStringConst        /* name */,
00631     VTypeMethods *      /* methods */
00632 #endif
00633 );
00634 
00635 VRepnKind VLookupType (
00636 #if NeedFunctionPrototypes
00637     VStringConst        /* name */
00638 #endif
00639 );
00640 
00641 #ifdef __cplusplus
00642 }
00643 #endif
00644 
00645 #endif /* V_Vlib_h */