IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 681


Ignore:
Timestamp:
May 13, 2004, 3:23:03 PM (22 years ago)
Author:
eugene
Message:

merged the concepts of a psFloatArray, psDoubleArray, etc into psVector.
changed the type names to be consistently in the form psS8, psF32, etc.
changed callback function names of the form fooCB to fooCallback

Location:
trunk/doc/pslib
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/pslib/Makefile

    r504 r681  
    1 # $Id: Makefile,v 1.2 2004-04-22 21:54:24 price Exp $
     1# $Id: Makefile,v 1.3 2004-05-14 01:23:03 eugene Exp $
    22
    33all : psLibDesign.pdf psLibADD.pdf
    … …  
    77        @if [ ! -f $*.aux ]; then \
    88                echo $(PDFLATEX) $*.tex; \
    9                 env TEXINPUTS=.:LaTeX:: $(PDFLATEX) $*.tex; \
     9                env TEXINPUTS=$(TEXINPUX).:LaTeX:: $(PDFLATEX) $*.tex; \
    1010        fi && env TEXINPUTS=.:LaTeX:: $(PDFLATEX) $*.tex || $(RM) $*.pdf
    1111#

  • trunk/doc/pslib/psLibSDRS.tex

    r673 r681  
    1 %%% $Id: psLibSDRS.tex,v 1.42 2004-05-13 23:42:23 price Exp $
     1%%% $Id: psLibSDRS.tex,v 1.43 2004-05-14 01:23:03 eugene Exp $
    22\documentclass[panstarrs]{panstarrs}
    33
    … …  
    317317\code{NULL} pointer. If they are unable to provide the requested
    318318memory they should attempt to obtain the desired memory by calling the
    319 routine registered by \code{psMemExhaustedSetCB} (see
     319routine registered by \code{psMemExhaustedSetCallback} (see
    320320\S\ref{secMemAdvanced}), and if still unsuccessful, call
    321321\code{psAbort()}.
    … …  
    338338%
    339339\begin{itemize}
    340 \item when insufficient memory is available (\code{psMemExhaustedCB})
    341 \item when a memory block is found to be corrupted (\code{psMemProblemCB})
    342 \item when a specified memory ID is allocated (\code{psMemAllocateCB})
    343 \item when a specified memory ID is freed (\code{psMemFreeCB})
     340\item when insufficient memory is available (\code{psMemExhaustedCallback})
     341\item when a memory block is found to be corrupted (\code{psMemProblemCallback})
     342\item when a specified memory ID is allocated (\code{psMemAllocateCallback})
     343\item when a specified memory ID is freed (\code{psMemFreeCallback})
    344344\end{itemize}
    345345%
    … …  
    353353four callbacks below.
    354354
    355 \subsubsubsection{\tt psMemExhaustedCB}
     355\subsubsubsection{\tt psMemExhaustedCallback}
    356356
    357357If not enough memory is available to satisfy a request by
    358358\code{psAlloc} or \code{psRealloc}, these functions attempt to find an
    359 alternative solution by calling the \code{psMemExhaustedCB}, a
     359alternative solution by calling the \code{psMemExhaustedCallback}, a
    360360function which may be set by the programmer in appropriate
    361361circumstances, rather than immediately fail.  The typical use of such
    … …  
    367367%
    368368\begin{verbatim}
    369 typedef void (*psMemExhaustedCB)(size_t size);
    370 psMemExhaustedCB psMemExhaustedCBSet(psMemExhaustedCB func);
     369typedef void (*psMemExhaustedCallback)(size_t size);
     370psMemExhaustedCallback psMemExhaustedCallbackSet(psMemExhaustedCallback func);
    371371\end{verbatim}
    372372%
    373373The callback function is called with the attempted size and is
    374374expected to return a pointer to the allocated memory or \code{NULL}.
    375 Until the callback function is set with \code{psMemExhaustedCBSet},
     375Until the callback function is set with \code{psMemExhaustedCallbackSet},
    376376the default callback function immediately returns \code{NULL}, in
    377377which case \code{psAlloc} will call \code{psAbort}.
    378378
    379 \subsubsubsection{\tt psMemProblemCB}
     379\subsubsubsection{\tt psMemProblemCallback}
    380380
    381381At various occasions, the memory manager can check the state of the
    382382memory stack.  If any of these checks discover that the memory stack
    383 is corrupted, the \code{psMemProblemCB} is called.  The callback
     383is corrupted, the \code{psMemProblemCallback} is called.  The callback
    384384has the following form:
    385385%
    386386\begin{verbatim}
    387 typedef void (*psMemProblemCB)(psMemBlock *ptr, char *file, int lineno);
    388 psMemProblemCB psMemProblemCBSet(psMemProblemCB func);
     387typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *file, int lineno);
     388psMemProblemCallback psMemProblemCallbackSet(psMemProblemCallback func);
    389389\end{verbatim}
    390390%
    … …  
    393393are expected.  The callback is for informational purposes only.  Where
    394394practical and efficient, the memory manager shall call the routine
    395 registered using \code{psMemProblemCBSet} whenever a corrupted block
     395registered using \code{psMemProblemCallbackSet} whenever a corrupted block
    396396of memory is discovered.  For example, doubly-freed blocks can be
    397397detected by checking \code{psMemBlock.refCounter}.
    398398
    399 \subsubsubsection{\tt psMemAllocateCB \& psMemFreeCB}
     399\subsubsubsection{\tt psMemAllocateCallback \& psMemFreeCallback}
    400400
    401401Two private variables, \code{p_psMemAllocateID} and
    … …  
    411411%
    412412\begin{verbatim}
    413 long psMemAllocateCBSetID(long id);
    414 long psMemFreeCBSetID(long id);
     413long psMemAllocateCallbackSetID(long id);
     414long psMemFreeCallbackSetID(long id);
    415415\end{verbatim}
    416416%
    … …  
    418418%
    419419\begin{verbatim}
    420 typedef long (*psMemAllocateCB)(const psMemBlock *ptr);
    421 psMemAllocateCB psMemAllocateCBSet(psMemAllocateCB func);
    422 typedef long (*psMemFreeCB)(const psMemBlock *ptr);
    423 psMemFreeCB psMemFreeCBSet(psMemFreeCB func);
     420typedef long (*psMemAllocateCallback)(const psMemBlock *ptr);
     421psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func);
     422typedef long (*psMemFreeCallback)(const psMemBlock *ptr);
     423psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func);
    424424\end{verbatim}
    425425%
    … …  
    428428\code{psMemAllocateIDSet} accept the desired ID value and return the
    429429old value to the user.  The return values of the handlers installed by
    430 \code{psMemAllocateCBSet} and \code{psMemFreeCBSet} are used to
     430\code{psMemAllocateCallbackSet} and \code{psMemFreeCallbackSet} are used to
    431431increment the values of \code{p_psMemAllocateID} and
    432432\code{p_psMemFreeID} respectively.  For example, a return value of
    … …  
    472472The routine \code{psMemCheckCorruption} checks the entire heap for
    473473corruption, calling the routine registered with
    474 \code{psMemProblemCBSet} for each block detected as being corrupted.
     474\code{psMemProblemCallbackSet} for each block detected as being corrupted.
    475475The return value is the number of corrupted blocks detected. If the
    476476argument \code{abort_on_error} is true, \code{psMemCheckCorruption}
    … …  
    12021202\begin{verbatim}
    12031203typedef enum {
    1204     PS_TYPE_CHAR,                       ///< Character
    1205     PS_TYPE_SHORT,                      ///< Short integer
    1206     PS_TYPE_INT,                        ///< Integer
    1207     PS_TYPE_LONG,                       ///< Long integer
    1208     PS_TYPE_UCHAR,                      ///< Unsigned character
    1209     PS_TYPE_USHORT,                     ///< Unsigned short integer
    1210     PS_TYPE_UINT,                       ///< Unsigned integer
    1211     PS_TYPE_ULONG,                      ///< Unsigned long integer
    1212     PS_TYPE_FLOAT,                      ///< Floating point
    1213     PS_TYPE_DOUBLE,                     ///< Double-precision floating point
    1214     PS_TYPE_COMPLEX,                    ///< Complex numbers consisting of floating point
    1215     PS_TYPE_OTHER,                      ///< Something else that's not supported for arithmetic
     1204    PS_TYPE_S8,                         ///< Character
     1205    PS_TYPE_S16,                        ///< Short integer
     1206    PS_TYPE_S32,                        ///< Integer
     1207    PS_TYPE_S64,                        ///< Long integer
     1208    PS_TYPE_U8,                         ///< Unsigned character
     1209    PS_TYPE_U16,                        ///< Unsigned short integer
     1210    PS_TYPE_U32,                        ///< Unsigned integer
     1211    PS_TYPE_U64,                        ///< Unsigned long integer
     1212    PS_TYPE_F32,                        ///< Floating point
     1213    PS_TYPE_F64,                        ///< Double-precision floating point
     1214    PS_TYPE_C32,                        ///< Complex numbers consisting of floating point
     1215    PS_TYPE_OTHER,                      ///< Something else that's not supported for arithmetic
    12161216} psElemType;
    12171217\end{verbatim}
    … …  
    12191219section~\ref{sec:arithmetic}. 
    12201220
    1221 \subsection{Arrays of Simple Types}
    1222 
    1223 We require several types of basic one-dimensional arrays: arrays of
    1224 values of type \code{int}, \code{float}, \code{double}, \code{complex
    1225 float}, and \code{void *}.  We have defined structures for these types
    1226 which are all equivalent.  We illustrate them with the example of
    1227 \code{psFloatArray}:
     1221\subsection{Simple Vectors}
     1222
     1223We require several related types of basic one-dimensional arrays:
     1224arrays of values of type \code{int}, \code{float}, \code{double},
     1225\code{complex float}, and \code{void *}.  We have defined a single
     1226structure, \code{psVector} to represent these concepts:
    12281227%
    12291228\begin{verbatim}
    12301229typedef struct {
    1231     psType type;                        ///< Type of data.  Must be first element
    1232     int nAlloc;                         ///< Total number of elements available
    1233     int n;                              ///< Number of elements in use
    1234     float *arr;                         ///< The array data
    1235 } psFloatArray;
     1230    psType type;                        ///< vector data type and dimension
     1231    const int n;                        ///< size of vector
     1232    const int nalloc;                   ///< data region relative to parent
     1233    union {
     1234        psF32 *arr;                     ///< Pointers to floating-point data (default)
     1235        psS8  *arr_S8;                  ///< Pointers to short-integer data
     1236        psS16 *arr_S16;                 ///< Pointers to short-integer data
     1237        psS32 *arr_S32;                 ///< Pointers to integer data
     1238        psS64 *arr_S64;                 ///< Pointers to long-integer data
     1239        psU8  *arr_U18;                 ///< Pointers to unsigned-short-integer data
     1240        psU16 *arr_U16;                 ///< Pointers to unsigned-short-integer data
     1241        psU32 *arr_U32;                 ///< Pointers to unsigned-integer data
     1242        psU64 *arr_U64;                 ///< Pointers to unsigned-long-integer data
     1243        psF32 *arr_F32;                 ///< Pointers to floating-point data
     1244        psF64 *arr_F64;                 ///< Pointers to double-precision data
     1245        psF32 *arr_C32;                 ///< Pointers to complex floating-point data
     1246        void **arr_v;
     1247    } arr;
     1248} psVector;
    12361249\end{verbatim}
    12371250%
    12381251In this structure, the argument \code{n} is the length of the array
    1239 (the number of elements); \code{nAlloc} is the number of elements
    1240 allocated ($s \ge n$).  The allocated memory is available at
    1241 \code{arr}.  The data type is defined by the first element,
    1242 \code{psType}.  The structure is associated with a constructor and a
    1243 destructor:
    1244 %
    1245 \begin{verbatim}
    1246 psFloatArray *psFloatArrayAlloc(int nAlloc);
    1247 psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int nAlloc);
    1248 void psFloatArrayFree(psFloatArray *restrict myArray);
    1249 \end{verbatim}
    1250 %
    1251 In these functions, \code{nAlloc} is the number of elements to
    1252 allocate.  For \code{psFloatArrayAlloc}, the value of
    1253 \code{psFloatArray.n} is set to 0.  For \code{psFloatArrayRealloc}, if
    1254 the value of \code{nAlloc} is smaller than the current value of
    1255 \code{psFloatArray.n}, then \code{psFloatArray.n} is set to
    1256 \code{nAlloc}, the array is adjusted down to match \code{nAlloc}, and
    1257 the extra elements are lost.  If \code{nAlloc} is larger than the
    1258 current value of \code{psFloatArray.n}, \code{psFloatArray.n} is left
    1259 intact.  If the value of \code{myArray} is \code{NULL}, then
    1260 \code{psFloatArrayRealloc} behaves like \code{psFloatArrayAlloc}.
    1261 
    1262 Basic one-dimensional arrays of all of the types listed above have
    1263 equivalent structures, constructors, and destructors to those for
    1264 \code{psFloatArray}, with the words \code{float} converted to the
    1265 appropriate type.  Thus we have:
    1266 \begin{verbatim}
    1267 psIntArray *psIntArrayAlloc(int nAlloc);
    1268 psFloatArray *psFloatArrayAlloc(int nAlloc);
    1269 psDoubleArray *psDoubleArrayAlloc(int nAlloc);
    1270 psComplexArray *psComplexArrayAlloc(int nAlloc);
    1271 \end{verbatim}
    1272 and so on for the other functions.  The collection of structures and
    1273 functions may be easily generated with C pre-processor macros.
     1252(the number of elements); \code{nalloc} is the number of elements
     1253allocated ($nalloc \ge n$).  The allocated memory is available in the
     1254union \code{arr} which consists of pointers to each of the defined
     1255primitive data types.  Note the parallelism in the names of the types,
     1256union elements, and the psElemType names.  This parallelism allows us
     1257to use automatic construction mechanisms effectively.  The data type
     1258is defined by the first element, \code{psType}.  The
     1259structure is associated with a constructor and a destructor:
     1260%
     1261\begin{verbatim}
     1262psVector *psVectorAlloc(int nalloc, psElemType type);
     1263psVector *psVectorRealloc(const psVector *vector, int nalloc);
     1264void psVectorFree(psVector *restrict vector);
     1265\end{verbatim}
     1266%
     1267In these functions, \code{nalloc} is the number of elements to
     1268allocate.  For \code{psVectorAlloc}, the value of \code{psVector.n} is
     1269set to 0.  For \code{psVectorRealloc}, if the value of \code{nalloc}
     1270is smaller than the current value of \code{psVector.n}, then
     1271\code{psVector.n} is set to \code{nalloc}, the array is adjusted down
     1272to match \code{nalloc}, and the extra elements are lost.  If
     1273\code{nalloc} is larger than the current value of \code{psVector.n},
     1274\code{psVector.n} is left intact.  If the value of \code{myArray} is
     1275\code{NULL}, then \code{psVectorRealloc} must return an error.
    12741276
    12751277\subsection{Arrays of Pointer Types}
    … …  
    13121314\code{refCounter}'s should be decremented) --- this is to account for
    13131315an array of heterogeneous types.
     1316
     1317\subsection{Simple Images}
     1318
     1319The most important data product produced by the telescope is an image.
     1320The simplest image is a 2-D collection of pixels, each with some
     1321value.  We require a basic image data type:
     1322
     1323\begin{verbatim}
     1324typedef struct psImage {
     1325    psType type;                        ///< image data type and dimension
     1326    const int ncols, nrows;             ///< size of image
     1327    const int x0, y0;                   ///< data region relative to parent
     1328    union {
     1329        psF32 **rows;                   ///< Pointers to floating-point data (default)
     1330        psS8  **rows_S8;                ///< Pointers to char data
     1331        psS16 **rows_S16;               ///< Pointers to short-integer data
     1332        psS32 **rows_S32;               ///< Pointers to integer data
     1333        psS64 **rows_S64;               ///< Pointers to long-integer data
     1334        psU8  **rows_U8;                ///< Pointers to unsigned-char data
     1335        psU16 **rows_U16;               ///< Pointers to unsigned-short-integer data
     1336        psU32 **rows_U32;               ///< Pointers to unsigned-integer data
     1337        psU64 **rows_U64;               ///< Pointers to unsigned-long-integer data
     1338        psF32 **rows_F32;               ///< Pointers to floating-point data
     1339        psF64 **rows_F64;               ///< Pointers to double-precision data
     1340        psC32 **rows_C32;               ///< Pointers to complex floating-point data
     1341    } rows;
     1342    const struct psImage *parent;       ///< parent, if a subimage
     1343    int Nchildren;                      ///< number of subimages
     1344    struct psImage **children;          ///< children of this region; array of Nchildren pointers
     1345} psImage;
     1346\end{verbatim}
     1347
     1348This structure represents an image consisting of a 2-D array of
     1349pixels.  The size of this array is given by the elements \code{(nrows,
     1350ncols)}.  The data type of the pixel is defined in the \code{psType
     1351type} entry (specifically, the \code{psElemType} member, \code{type};
     1352see \ref{sec:arithmetic}).  (n.b. that for FITS images, these values
     1353are restricted to the datatypes equivalent to the valid BITPIX values
     13548, 16, 32, -32, -64).  The image represented in the data structure may
     1355represent a subset of the pixels in a complete array, in which case
     1356the image is considered to be the child of that parent array.  The
     1357offset of the \code{(0,0)} pixel in this array relative to the parent
     1358array is given by the elements \code{(x0,y0)}: \code{x0} is the
     1359starting column number in the parent image while \code{y0} is the
     1360starting row number.  The structure may include references to
     1361subrasters (\code{children, Nchildren}) and/or to a containing array
     1362(\code{parent}).  Unless this is image is a child of another image
     1363(represents a subset of the pixels of another image), the image data
     1364is allocated in a contiguous block.
     1365
     1366Create an image of a specified width, height, and data type.  This
     1367function must allow any of the valid image data types and not restrict
     1368to the valid FITS BITPIX types.
     1369\begin{verbatim}
     1370psImage *psImageAlloc (int width, int height, psElemType type);
     1371\end{verbatim}
     1372where \code{width} and \code{height} specify the size of the image and
     1373\code{type} specifies the data type and the image dimensionality
     1374(which must be 2).
     1375
     1376Free the memory associated with a specific image, including the pixel
     1377data. Free the children of the image if they exist.
     1378\begin{verbatim}
     1379void psImageFree(psImage *image);
     1380\end{verbatim}
     1381
     1382Free only the pixels for a specified image:
     1383\begin{verbatim}
     1384psImage *psImageFreePixels(psImage *image);
     1385\end{verbatim}
    13141386
    13151387\subsection{Doubly-linked lists}
    … …  
    22482320%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    22492321
    2250 \subsection{Simple Images}
    2251 
    2252 The most important data product produced by the telescope is an image.
    2253 The simplest image is a 2-D collection of pixels, each with some
    2254 value.  We require a basic image data type:
    2255 
    2256 \begin{verbatim}
    2257 typedef struct psImage {
    2258     psType type;                        ///< image data type and dimension
    2259     const int nx, ny;                   ///< size of image
    2260     const int x0, y0;                   ///< data region relative to parent
    2261     union {
    2262         float **rows;                   ///< Pointers to floating-point data (default)
    2263         short int **rows_si;            ///< Pointers to short-integer data
    2264         int **rows_i;                   ///< Pointers to integer data
    2265         long int **rows_li;             ///< Pointers to long-integer data
    2266         unsigned short int **rows_usi;  ///< Pointers to unsigned-short-integer data
    2267         unsigned int **rows_ui;         ///< Pointers to unsigned-integer data
    2268         unsigned long int **rows_uli;   ///< Pointers to unsigned-long-integer data
    2269         float **rows_f;                 ///< Pointers to floating-point data
    2270         double **rows_d;                ///< Pointers to double-precision data
    2271         complex float **rows_complex;   ///< Pointers to complex floating-point data
    2272     } rows;
    2273     const struct psImage *parent;       ///< parent, if a subimage
    2274     int Nchildren;                      ///< number of subimages
    2275     struct psImage *children;           ///< children of this region; array of Nchildren pointers
    2276 } psImage;
    2277 \end{verbatim}
    2278 
    2279 This structure represents an image consisting of a 2-D array of
    2280 pixels.  The size of this array is given by the elements \code{(nx,
    2281 ny)}.  The data type of the pixel is defined in the \code{psType type}
    2282 entry (specifically, the \code{psElemType} member, \code{type}; see
    2283 \ref{sec:arithmetic}).  (n.b. that for FITS images, these values are
    2284 restricted to the datatypes equivalent to the valid BITPIX values 8,
    2285 16, 32, -32, -64).  The image represented in the data structure may
    2286 represent a subset of the pixels in a complete array, in which case
    2287 the image is considered to be the child of that parent array.  The
    2288 offset of the \code{(0,0)} pixel in this array relative to the parent
    2289 array is given by the elements \code{(x0,y0)}.  The structure may
    2290 include references to subrasters (\code{children, Nchildren}) and/or
    2291 to a containing array (\code{parent}).  Unless this is image is a
    2292 child of another image (represents a subset of the pixels of another
    2293 image), the image data is allocated in a contiguous block.
     2322\subsection{Image Operations}
     2323
     2324\subsubsection{Image Structure Manipulation}
    22942325
    22952326We require a variety of functions to manipulate these image
    … …  
    22972328various manipulations of the pixels.  The required functions are
    22982329listed below, and fall into several categories.
    2299 
    2300 \subsubsection{Image Structure Manipulation}
    2301 
    2302 Create an image of a specified width, height, and data type.  This
    2303 function must allow any of the valid image data types and not restrict
    2304 to the valid FITS BITPIX types.
    2305 \begin{verbatim}
    2306 psImage *psImageAlloc (int nx, int ny, psElemType type);
    2307 \end{verbatim}
    2308 where \code{nx} and \code{ny} specify the size of the image and
    2309 \code{type} specifies the data type and the image dimensions (which
    2310 must be 2).
    23112330
    23122331Define a subimage of the specified area of the given image.  This
    … …  
    23212340contained within the raster of the parent image.  Note that the
    23222341\code{refCounter} for the parent should be incremented.
    2323 
    2324 Free the memory associated with a specific image, including the pixel
    2325 data. Free the children of the image if they exist.
    2326 \begin{verbatim}
    2327 void psImageFree(psImage *image);
    2328 \end{verbatim}
    2329 
    2330 Free only the pixels for a specified image:
    2331 \begin{verbatim}
    2332 psImage *psImageFreePixels(psImage *image);
    2333 \end{verbatim}
    23342342
    23352343Create a copy of the specified image, converting the type in the
Note: See TracChangeset for help on using the changeset viewer.