Index: /trunk/doc/pslib/Makefile =================================================================== --- /trunk/doc/pslib/Makefile (revision 680) +++ /trunk/doc/pslib/Makefile (revision 681) @@ -1,3 +1,3 @@ -# $Id: Makefile,v 1.2 2004-04-22 21:54:24 price Exp $ +# $Id: Makefile,v 1.3 2004-05-14 01:23:03 eugene Exp $ all : psLibDesign.pdf psLibADD.pdf @@ -7,5 +7,5 @@ @if [ ! -f $*.aux ]; then \ echo $(PDFLATEX) $*.tex; \ - env TEXINPUTS=.:LaTeX:: $(PDFLATEX) $*.tex; \ + env TEXINPUTS=$(TEXINPUX).:LaTeX:: $(PDFLATEX) $*.tex; \ fi && env TEXINPUTS=.:LaTeX:: $(PDFLATEX) $*.tex || $(RM) $*.pdf # Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 680) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 681) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.42 2004-05-13 23:42:23 price Exp $ +%%% $Id: psLibSDRS.tex,v 1.43 2004-05-14 01:23:03 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -317,5 +317,5 @@ \code{NULL} pointer. If they are unable to provide the requested memory they should attempt to obtain the desired memory by calling the -routine registered by \code{psMemExhaustedSetCB} (see +routine registered by \code{psMemExhaustedSetCallback} (see \S\ref{secMemAdvanced}), and if still unsuccessful, call \code{psAbort()}. @@ -338,8 +338,8 @@ % \begin{itemize} -\item when insufficient memory is available (\code{psMemExhaustedCB}) -\item when a memory block is found to be corrupted (\code{psMemProblemCB}) -\item when a specified memory ID is allocated (\code{psMemAllocateCB}) -\item when a specified memory ID is freed (\code{psMemFreeCB}) +\item when insufficient memory is available (\code{psMemExhaustedCallback}) +\item when a memory block is found to be corrupted (\code{psMemProblemCallback}) +\item when a specified memory ID is allocated (\code{psMemAllocateCallback}) +\item when a specified memory ID is freed (\code{psMemFreeCallback}) \end{itemize} % @@ -353,9 +353,9 @@ four callbacks below. -\subsubsubsection{\tt psMemExhaustedCB} +\subsubsubsection{\tt psMemExhaustedCallback} If not enough memory is available to satisfy a request by \code{psAlloc} or \code{psRealloc}, these functions attempt to find an -alternative solution by calling the \code{psMemExhaustedCB}, a +alternative solution by calling the \code{psMemExhaustedCallback}, a function which may be set by the programmer in appropriate circumstances, rather than immediately fail. The typical use of such @@ -367,24 +367,24 @@ % \begin{verbatim} -typedef void (*psMemExhaustedCB)(size_t size); -psMemExhaustedCB psMemExhaustedCBSet(psMemExhaustedCB func); +typedef void (*psMemExhaustedCallback)(size_t size); +psMemExhaustedCallback psMemExhaustedCallbackSet(psMemExhaustedCallback func); \end{verbatim} % The callback function is called with the attempted size and is expected to return a pointer to the allocated memory or \code{NULL}. -Until the callback function is set with \code{psMemExhaustedCBSet}, +Until the callback function is set with \code{psMemExhaustedCallbackSet}, the default callback function immediately returns \code{NULL}, in which case \code{psAlloc} will call \code{psAbort}. -\subsubsubsection{\tt psMemProblemCB} +\subsubsubsection{\tt psMemProblemCallback} At various occasions, the memory manager can check the state of the memory stack. If any of these checks discover that the memory stack -is corrupted, the \code{psMemProblemCB} is called. The callback +is corrupted, the \code{psMemProblemCallback} is called. The callback has the following form: % \begin{verbatim} -typedef void (*psMemProblemCB)(psMemBlock *ptr, char *file, int lineno); -psMemProblemCB psMemProblemCBSet(psMemProblemCB func); +typedef void (*psMemProblemCallback)(psMemBlock *ptr, char *file, int lineno); +psMemProblemCallback psMemProblemCallbackSet(psMemProblemCallback func); \end{verbatim} % @@ -393,9 +393,9 @@ are expected. The callback is for informational purposes only. Where practical and efficient, the memory manager shall call the routine -registered using \code{psMemProblemCBSet} whenever a corrupted block +registered using \code{psMemProblemCallbackSet} whenever a corrupted block of memory is discovered. For example, doubly-freed blocks can be detected by checking \code{psMemBlock.refCounter}. -\subsubsubsection{\tt psMemAllocateCB \& psMemFreeCB} +\subsubsubsection{\tt psMemAllocateCallback \& psMemFreeCallback} Two private variables, \code{p_psMemAllocateID} and @@ -411,6 +411,6 @@ % \begin{verbatim} -long psMemAllocateCBSetID(long id); -long psMemFreeCBSetID(long id); +long psMemAllocateCallbackSetID(long id); +long psMemFreeCallbackSetID(long id); \end{verbatim} % @@ -418,8 +418,8 @@ % \begin{verbatim} -typedef long (*psMemAllocateCB)(const psMemBlock *ptr); -psMemAllocateCB psMemAllocateCBSet(psMemAllocateCB func); -typedef long (*psMemFreeCB)(const psMemBlock *ptr); -psMemFreeCB psMemFreeCBSet(psMemFreeCB func); +typedef long (*psMemAllocateCallback)(const psMemBlock *ptr); +psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func); +typedef long (*psMemFreeCallback)(const psMemBlock *ptr); +psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func); \end{verbatim} % @@ -428,5 +428,5 @@ \code{psMemAllocateIDSet} accept the desired ID value and return the old value to the user. The return values of the handlers installed by -\code{psMemAllocateCBSet} and \code{psMemFreeCBSet} are used to +\code{psMemAllocateCallbackSet} and \code{psMemFreeCallbackSet} are used to increment the values of \code{p_psMemAllocateID} and \code{p_psMemFreeID} respectively. For example, a return value of @@ -472,5 +472,5 @@ The routine \code{psMemCheckCorruption} checks the entire heap for corruption, calling the routine registered with -\code{psMemProblemCBSet} for each block detected as being corrupted. +\code{psMemProblemCallbackSet} for each block detected as being corrupted. The return value is the number of corrupted blocks detected. If the argument \code{abort_on_error} is true, \code{psMemCheckCorruption} @@ -1202,16 +1202,16 @@ \begin{verbatim} typedef enum { - PS_TYPE_CHAR, ///< Character - PS_TYPE_SHORT, ///< Short integer - PS_TYPE_INT, ///< Integer - PS_TYPE_LONG, ///< Long integer - PS_TYPE_UCHAR, ///< Unsigned character - PS_TYPE_USHORT, ///< Unsigned short integer - PS_TYPE_UINT, ///< Unsigned integer - PS_TYPE_ULONG, ///< Unsigned long integer - PS_TYPE_FLOAT, ///< Floating point - PS_TYPE_DOUBLE, ///< Double-precision floating point - PS_TYPE_COMPLEX, ///< Complex numbers consisting of floating point - PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic + PS_TYPE_S8, ///< Character + PS_TYPE_S16, ///< Short integer + PS_TYPE_S32, ///< Integer + PS_TYPE_S64, ///< Long integer + PS_TYPE_U8, ///< Unsigned character + PS_TYPE_U16, ///< Unsigned short integer + PS_TYPE_U32, ///< Unsigned integer + PS_TYPE_U64, ///< Unsigned long integer + PS_TYPE_F32, ///< Floating point + PS_TYPE_F64, ///< Double-precision floating point + PS_TYPE_C32, ///< Complex numbers consisting of floating point + PS_TYPE_OTHER, ///< Something else that's not supported for arithmetic } psElemType; \end{verbatim} @@ -1219,57 +1219,59 @@ section~\ref{sec:arithmetic}. -\subsection{Arrays of Simple Types} - -We require several types of basic one-dimensional arrays: arrays of -values of type \code{int}, \code{float}, \code{double}, \code{complex -float}, and \code{void *}. We have defined structures for these types -which are all equivalent. We illustrate them with the example of -\code{psFloatArray}: +\subsection{Simple Vectors} + +We require several related types of basic one-dimensional arrays: +arrays of values of type \code{int}, \code{float}, \code{double}, +\code{complex float}, and \code{void *}. We have defined a single +structure, \code{psVector} to represent these concepts: % \begin{verbatim} typedef struct { - psType type; ///< Type of data. Must be first element - int nAlloc; ///< Total number of elements available - int n; ///< Number of elements in use - float *arr; ///< The array data -} psFloatArray; + psType type; ///< vector data type and dimension + const int n; ///< size of vector + const int nalloc; ///< data region relative to parent + union { + psF32 *arr; ///< Pointers to floating-point data (default) + psS8 *arr_S8; ///< Pointers to short-integer data + psS16 *arr_S16; ///< Pointers to short-integer data + psS32 *arr_S32; ///< Pointers to integer data + psS64 *arr_S64; ///< Pointers to long-integer data + psU8 *arr_U18; ///< Pointers to unsigned-short-integer data + psU16 *arr_U16; ///< Pointers to unsigned-short-integer data + psU32 *arr_U32; ///< Pointers to unsigned-integer data + psU64 *arr_U64; ///< Pointers to unsigned-long-integer data + psF32 *arr_F32; ///< Pointers to floating-point data + psF64 *arr_F64; ///< Pointers to double-precision data + psF32 *arr_C32; ///< Pointers to complex floating-point data + void **arr_v; + } arr; +} psVector; \end{verbatim} % In this structure, the argument \code{n} is the length of the array -(the number of elements); \code{nAlloc} is the number of elements -allocated ($s \ge n$). The allocated memory is available at -\code{arr}. The data type is defined by the first element, -\code{psType}. The structure is associated with a constructor and a -destructor: -% -\begin{verbatim} -psFloatArray *psFloatArrayAlloc(int nAlloc); -psFloatArray *psFloatArrayRealloc(psFloatArray *myArray, int nAlloc); -void psFloatArrayFree(psFloatArray *restrict myArray); -\end{verbatim} -% -In these functions, \code{nAlloc} is the number of elements to -allocate. For \code{psFloatArrayAlloc}, the value of -\code{psFloatArray.n} is set to 0. For \code{psFloatArrayRealloc}, if -the value of \code{nAlloc} is smaller than the current value of -\code{psFloatArray.n}, then \code{psFloatArray.n} is set to -\code{nAlloc}, the array is adjusted down to match \code{nAlloc}, and -the extra elements are lost. If \code{nAlloc} is larger than the -current value of \code{psFloatArray.n}, \code{psFloatArray.n} is left -intact. If the value of \code{myArray} is \code{NULL}, then -\code{psFloatArrayRealloc} behaves like \code{psFloatArrayAlloc}. - -Basic one-dimensional arrays of all of the types listed above have -equivalent structures, constructors, and destructors to those for -\code{psFloatArray}, with the words \code{float} converted to the -appropriate type. Thus we have: -\begin{verbatim} -psIntArray *psIntArrayAlloc(int nAlloc); -psFloatArray *psFloatArrayAlloc(int nAlloc); -psDoubleArray *psDoubleArrayAlloc(int nAlloc); -psComplexArray *psComplexArrayAlloc(int nAlloc); -\end{verbatim} -and so on for the other functions. The collection of structures and -functions may be easily generated with C pre-processor macros. +(the number of elements); \code{nalloc} is the number of elements +allocated ($nalloc \ge n$). The allocated memory is available in the +union \code{arr} which consists of pointers to each of the defined +primitive data types. Note the parallelism in the names of the types, +union elements, and the psElemType names. This parallelism allows us +to use automatic construction mechanisms effectively. The data type +is defined by the first element, \code{psType}. The +structure is associated with a constructor and a destructor: +% +\begin{verbatim} +psVector *psVectorAlloc(int nalloc, psElemType type); +psVector *psVectorRealloc(const psVector *vector, int nalloc); +void psVectorFree(psVector *restrict vector); +\end{verbatim} +% +In these functions, \code{nalloc} is the number of elements to +allocate. For \code{psVectorAlloc}, the value of \code{psVector.n} is +set to 0. For \code{psVectorRealloc}, if the value of \code{nalloc} +is smaller than the current value of \code{psVector.n}, then +\code{psVector.n} is set to \code{nalloc}, the array is adjusted down +to match \code{nalloc}, and the extra elements are lost. If +\code{nalloc} is larger than the current value of \code{psVector.n}, +\code{psVector.n} is left intact. If the value of \code{myArray} is +\code{NULL}, then \code{psVectorRealloc} must return an error. \subsection{Arrays of Pointer Types} @@ -1312,4 +1314,74 @@ \code{refCounter}'s should be decremented) --- this is to account for an array of heterogeneous types. + +\subsection{Simple Images} + +The most important data product produced by the telescope is an image. +The simplest image is a 2-D collection of pixels, each with some +value. We require a basic image data type: + +\begin{verbatim} +typedef struct psImage { + psType type; ///< image data type and dimension + const int ncols, nrows; ///< size of image + const int x0, y0; ///< data region relative to parent + union { + psF32 **rows; ///< Pointers to floating-point data (default) + psS8 **rows_S8; ///< Pointers to char data + psS16 **rows_S16; ///< Pointers to short-integer data + psS32 **rows_S32; ///< Pointers to integer data + psS64 **rows_S64; ///< Pointers to long-integer data + psU8 **rows_U8; ///< Pointers to unsigned-char data + psU16 **rows_U16; ///< Pointers to unsigned-short-integer data + psU32 **rows_U32; ///< Pointers to unsigned-integer data + psU64 **rows_U64; ///< Pointers to unsigned-long-integer data + psF32 **rows_F32; ///< Pointers to floating-point data + psF64 **rows_F64; ///< Pointers to double-precision data + psC32 **rows_C32; ///< Pointers to complex floating-point data + } rows; + const struct psImage *parent; ///< parent, if a subimage + int Nchildren; ///< number of subimages + struct psImage **children; ///< children of this region; array of Nchildren pointers +} psImage; +\end{verbatim} + +This structure represents an image consisting of a 2-D array of +pixels. The size of this array is given by the elements \code{(nrows, +ncols)}. The data type of the pixel is defined in the \code{psType +type} entry (specifically, the \code{psElemType} member, \code{type}; +see \ref{sec:arithmetic}). (n.b. that for FITS images, these values +are restricted to the datatypes equivalent to the valid BITPIX values +8, 16, 32, -32, -64). The image represented in the data structure may +represent a subset of the pixels in a complete array, in which case +the image is considered to be the child of that parent array. The +offset of the \code{(0,0)} pixel in this array relative to the parent +array is given by the elements \code{(x0,y0)}: \code{x0} is the +starting column number in the parent image while \code{y0} is the +starting row number. The structure may include references to +subrasters (\code{children, Nchildren}) and/or to a containing array +(\code{parent}). Unless this is image is a child of another image +(represents a subset of the pixels of another image), the image data +is allocated in a contiguous block. + +Create an image of a specified width, height, and data type. This +function must allow any of the valid image data types and not restrict +to the valid FITS BITPIX types. +\begin{verbatim} +psImage *psImageAlloc (int width, int height, psElemType type); +\end{verbatim} +where \code{width} and \code{height} specify the size of the image and +\code{type} specifies the data type and the image dimensionality +(which must be 2). + +Free the memory associated with a specific image, including the pixel +data. Free the children of the image if they exist. +\begin{verbatim} +void psImageFree(psImage *image); +\end{verbatim} + +Free only the pixels for a specified image: +\begin{verbatim} +psImage *psImageFreePixels(psImage *image); +\end{verbatim} \subsection{Doubly-linked lists} @@ -2248,48 +2320,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Simple Images} - -The most important data product produced by the telescope is an image. -The simplest image is a 2-D collection of pixels, each with some -value. We require a basic image data type: - -\begin{verbatim} -typedef struct psImage { - psType type; ///< image data type and dimension - const int nx, ny; ///< size of image - const int x0, y0; ///< data region relative to parent - union { - float **rows; ///< Pointers to floating-point data (default) - short int **rows_si; ///< Pointers to short-integer data - int **rows_i; ///< Pointers to integer data - long int **rows_li; ///< Pointers to long-integer data - unsigned short int **rows_usi; ///< Pointers to unsigned-short-integer data - unsigned int **rows_ui; ///< Pointers to unsigned-integer data - unsigned long int **rows_uli; ///< Pointers to unsigned-long-integer data - float **rows_f; ///< Pointers to floating-point data - double **rows_d; ///< Pointers to double-precision data - complex float **rows_complex; ///< Pointers to complex floating-point data - } rows; - const struct psImage *parent; ///< parent, if a subimage - int Nchildren; ///< number of subimages - struct psImage *children; ///< children of this region; array of Nchildren pointers -} psImage; -\end{verbatim} - -This structure represents an image consisting of a 2-D array of -pixels. The size of this array is given by the elements \code{(nx, -ny)}. The data type of the pixel is defined in the \code{psType type} -entry (specifically, the \code{psElemType} member, \code{type}; see -\ref{sec:arithmetic}). (n.b. that for FITS images, these values are -restricted to the datatypes equivalent to the valid BITPIX values 8, -16, 32, -32, -64). The image represented in the data structure may -represent a subset of the pixels in a complete array, in which case -the image is considered to be the child of that parent array. The -offset of the \code{(0,0)} pixel in this array relative to the parent -array is given by the elements \code{(x0,y0)}. The structure may -include references to subrasters (\code{children, Nchildren}) and/or -to a containing array (\code{parent}). Unless this is image is a -child of another image (represents a subset of the pixels of another -image), the image data is allocated in a contiguous block. +\subsection{Image Operations} + +\subsubsection{Image Structure Manipulation} We require a variety of functions to manipulate these image @@ -2297,16 +2328,4 @@ various manipulations of the pixels. The required functions are listed below, and fall into several categories. - -\subsubsection{Image Structure Manipulation} - -Create an image of a specified width, height, and data type. This -function must allow any of the valid image data types and not restrict -to the valid FITS BITPIX types. -\begin{verbatim} -psImage *psImageAlloc (int nx, int ny, psElemType type); -\end{verbatim} -where \code{nx} and \code{ny} specify the size of the image and -\code{type} specifies the data type and the image dimensions (which -must be 2). Define a subimage of the specified area of the given image. This @@ -2321,15 +2340,4 @@ contained within the raster of the parent image. Note that the \code{refCounter} for the parent should be incremented. - -Free the memory associated with a specific image, including the pixel -data. Free the children of the image if they exist. -\begin{verbatim} -void psImageFree(psImage *image); -\end{verbatim} - -Free only the pixels for a specified image: -\begin{verbatim} -psImage *psImageFreePixels(psImage *image); -\end{verbatim} Create a copy of the specified image, converting the type in the