Index: /trunk/doc/pslib/psLibSDRS.tex =================================================================== --- /trunk/doc/pslib/psLibSDRS.tex (revision 921) +++ /trunk/doc/pslib/psLibSDRS.tex (revision 922) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.50 2004-06-03 03:14:54 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.51 2004-06-08 19:38:45 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -362,11 +362,23 @@ The callback functions are defined in terms of specific callback types, specified below. The callbacks are set using functions with -names of the form \code{psCallbackSet}. In all cases, the -`\code{Set}' routine takes a pointer to the desired callback function -and returns a pointer to the one that was previously installed. The -defaults for each of these callbacks is \code{NULL}, in which case the -corresponding callback is skipped. If the function pointer passed to -the functions above is \code{NULL}, the default behavior is set. We -discuss the use of each of the four callbacks below. +names of the form \code{psCallbackSet}. In all cases, the \code{Set} +routine takes a pointer to the desired callback function and returns a +pointer to the one that was previously installed. The default +functions for each of these callbacks is listed below: +% +\begin{itemize} +\item \code{psMemExhaustedCallbackDefault} +\item \code{psMemProblemCallbackDefault} +\item \code{psMemAllocateCallbackDefault} +\item \code{psMemFreeCallbackDefault} +\end{itemize} +% +and have the behavior of immediately returning \code{NULL}, as if the +callback had been skipped. If the function pointer passed to the +functions above is \code{NULL}, the callback must be reset to the +default callback function. The named default callbacks may be used in +within a debugger to catch these conditions by breaking when the +functions are called. We discuss the use of each of the four +callbacks below. \subsubsubsection{\tt psMemExhaustedCallback} @@ -1014,6 +1026,6 @@ \subsection{Abort} -\code{psAbort}, must call \code{psMsgLog} with a -level of \code{PS_LOG_ABORT}, and then call \code{abort}. +\code{psAbort}, must call \code{psLogMsgV} with a level of +\code{PS_LOG_ABORT}, and then call \code{abort}. \begin{verbatim} @@ -1232,18 +1244,18 @@ \subsection{Doubly-linked lists} -\label{sec:psDlist} - -\PS{} supports doubly linked lists through a type \code{psDlist}: +\label{sec:psList} + +\PS{} supports doubly linked lists through a type \code{psList}: % \begin{verbatim} typedef struct { int n; ///< number of elements on list - psDlistElem *head; ///< first element on list (may be NULL) - psDlistElem *tail; ///< last element on list (may be NULL) - psDlistElem *iter; ///< iteration cursor -} psDlist; -\end{verbatim} -% -The type \code{psDlist} represents the container of the list. It has + psListElem *head; ///< first element on list (may be NULL) + psListElem *tail; ///< last element on list (may be NULL) + psListElem *iter; ///< iteration cursor +} psList; +\end{verbatim} +% +The type \code{psList} represents the container of the list. It has a pointer to the first element in the linked list (\code{head}), a pointer to the last element in the list (\code{tail}), an entry for @@ -1251,12 +1263,12 @@ number of elements in the list (\code{n}). -The elements of the list are defined by the type \code{psDlistElem}: -% -\begin{verbatim} -typedef struct psDlistElem { - struct psDlistElem *prev; ///< previous link in list - struct psDlistElem *next; ///< next link in list +The elements of the list are defined by the type \code{psListElem}: +% +\begin{verbatim} +typedef struct psListElem { + struct psListElem *prev; ///< previous link in list + struct psListElem *next; ///< next link in list void *data; ///< real data item -} psDlistElem; +} psListElem; \end{verbatim} % @@ -1267,19 +1279,19 @@ \begin{verbatim} -psDlist *psDlistAlloc(void *data); +psList *psListAlloc(void *data); \end{verbatim} Create a list. This function may take a pointer to a data item, or it -may take \code{NULL}. The allocator creates both the \code{psDlist} +may take \code{NULL}. The allocator creates both the \code{psList} and the first element in the list, pointed to by both -\code{psDlist.head} and \code{psDlist.tail}. If the data entry is +\code{psList.head} and \code{psList.tail}. If the data entry is \code{NULL}, then an empty list, with both pointers are set to \code{NULL} should be created. \begin{verbatim} -psDlist *psDlistAdd(psDlist *list, void *data, int where); +psList *psListAdd(psList *list, void *data, int where); \end{verbatim} Add an entry to the list with this function, which takes a pointer to the list and also returns a pointer to the list. The returned pointer -must be used as the value of \code{psDlist} may have changed. The +must be used as the value of \code{psList} may have changed. The value of \code{where} specifies if the specified data item should be placed on the front of the list (\code{PS_DLIST_HEAD}), at the end of @@ -1290,5 +1302,5 @@ \begin{verbatim} -void *psDlistGet(psDlist *list, int which); +void *psListGet(psList *list, int which); \end{verbatim} A data item may be retrieved from the list with this function. The @@ -1300,5 +1312,5 @@ \begin{verbatim} -void *psDlistRemove(psDlist *list, void *data, int which); +void *psListRemove(psList *list, void *data, int which); \end{verbatim} A data item may be removed from the list with this function. The @@ -1311,13 +1323,13 @@ *data}. -All data items placed onto lists (\code{psDlistAdd}) must have their +All data items placed onto lists (\code{psListAdd}) must have their reference counters (section \ref{secMemRefcounter}) incremented. When -elements are removed from a list with \code{psDlistRemove}, they must +elements are removed from a list with \code{psListRemove}, they must have their reference counters decremented. The action of retrieving -data from a list (with \code{psDlistGet}) must not affect their +data from a list (with \code{psListGet}) must not affect their reference counter. \begin{verbatim} -void psDlistFree(psDlist *list, void (*elemFree)(void *)); +void psListFree(psList *list, void (*elemFree)(void *)); \end{verbatim} A complete list may be freed with this destructor. If the element @@ -1327,16 +1339,16 @@ \begin{verbatim} -psVector *psDlistToVector(psDlist *dlist); -psDlist *psVectorToDlist(psVector *vector); +psVector *psListToVector(psList *dlist); +psList *psVectorToDlist(psVector *vector); \end{verbatim} These two functions are available to convert between the -\code{psDlist} and \code{psVector} containers. These functions do not +\code{psList} and \code{psVector} containers. These functions do not free the elements or destroy the input collection. Rather, they increment the reference counter for each of the elements. \begin{verbatim} -void psDlistSetIterator(psDlist *list, int where, int which); -void *psDlistGetNext(psDlist *list, int which); -void *psDlistGetPrev(psDlist *list, int which); +void psListSetIterator(psList *list, int where, int which); +void *psListGetNext(psList *list, int which); +void *psListGetPrev(psList *list, int which); \end{verbatim} Iteration over all elements of the list using the iteration cursor @@ -1348,11 +1360,11 @@ returning the data item from the resulting list entry, or returning \code{NULL} at the end of the list. Explicit traversal of the list -using the \code{psDlistElem}s \code{prev} and \code{next} pointers is +using the \code{psListElem}s \code{prev} and \code{next} pointers is also supported. \begin{verbatim} -psDlist *psDlistSort(psDlist *list, int (*compare)(const void *a, const void *b) ); -\end{verbatim} -A list may be sorted using \code{psDlistSort}, which requires the +psList *psListSort(psList *list, int (*compare)(const void *a, const void *b) ); +\end{verbatim} +A list may be sorted using \code{psListSort}, which requires the specification of a comparison function to specify how the objects on the list should be sorted. The motivation is primarily to be able to @@ -1449,5 +1461,5 @@ The function \begin{verbatim} -psDlist *psHashKeylist(psHast *table); +psList *psHashKeylist(psHast *table); \end{verbatim} returns the complete list of defined keys associated with the @@ -1980,6 +1992,8 @@ is derived from the statistics of the pixels at that direction coordinate. The statistic used to derive the output vector value is -specified by \code{stats}. This function must be defined for the -following types: \code{psU8}, \code{psU16}, \code{psF32}, \code{psF64}. +specified by \code{stats}. Only one of the statistics choices may be +specified, otherwise the function must return an error. This function +must be defined for the following types: \code{psU8}, \code{psU16}, +\code{psF32}, \code{psF64}. \begin{verbatim} @@ -1989,13 +2003,15 @@ \end{verbatim} Extract pixels from an image along a line to a vector (array of -floats). The vector \code{(xs,ys)} - \code{(xe,ye)} forms the basis of -the output vector. Pixels are considered in a rectangular region of -width \code{dw} about this vector. The input region is collapsed in -the perpendicular direction, and each element of the output vector +floats). The vector \code{(xs,ys)} - \code{(xe,ye)} forms the basis +of the output vector. Pixels are considered in a rectangular region +of width \code{dw} about this vector. The input region is collapsed +in the perpendicular direction, and each element of the output vector represents pixel-sized boxes, where the value is derived from the statistics of the pixels interpolated along the perpendicular direction. The statistic used to derive the output vector value is -specified by \code{stats}. This function must be defined for the -following types: \code{psU8}, \code{psU16}, \code{psF32}, \code{psF64} +specified by \code{stats}. Only one of the statistics choices may be +specified, otherwise the function must return an error. This function +must be defined for the following types: \code{psU8}, \code{psU16}, +\code{psF32}, \code{psF64} \begin{verbatim} @@ -2008,6 +2024,8 @@ the image pixel coordinate \code{x,y}, and have width \code{dr}. The number of annuli is $radius / dr$. The statistic used to derive the -output vector value is specified by \code{stats}. This function must be defined for the -following types: \code{psU8}, \code{psU16}, \code{psF32}, \code{psF64}. +output vector value is specified by \code{stats}. Only one of the +statistics choices may be specified, otherwise the function must +return an error. This function must be defined for the following +types: \code{psU8}, \code{psU16}, \code{psF32}, \code{psF64}. \subsubsection{Image Geometry Manipulation} @@ -2023,7 +2041,9 @@ Each pixel in the output image is derived from the statistics of the corresponding set of input image pixels based on the statistics -specified by \code{stats}. This function must be defined for the -following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, -\code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. +specified by \code{stats}. Only one of the statistics choices may be +specified, otherwise the function must return an error. This function +must be defined for the following types: \code{psU8}, \code{psU16}, +\code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, \code{psC32}, +\code{psC64}. \begin{verbatim} @@ -2162,6 +2182,6 @@ \code{+Inf} or \code{-Inf} values are set to the specified value. Returns the number of clipped pixels. This function must be defined -for the following types: \code{psU8}, \code{psU16}, \code{psS8}, -\code{psS16}, \code{psF32}, \code{psF64}, \code{psC32}, \code{psC64}. +for the following types: \code{psF32}, \code{psF64}, \code{psC32}, +\code{psC64}. \begin{verbatim} @@ -2178,5 +2198,7 @@ This function must be defined for the following types: \code{psU8}, \code{psU16}, \code{psS8}, \code{psS16}, \code{psF32}, \code{psF64}, -\code{psC32}, \code{psC64}. +\code{psC32}, \code{psC64}. The two input images must have the same +datatype and the output image must be constructed with that same +datatype. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2394,5 +2416,5 @@ \end{verbatim} -The output from a FFT and power spectrum shall be of the same size as +The output from a FFT and power spectrum must be of the same size as the input. In the future, if this adversely affects performance, this will be revised so that the redundant information will be neglected. @@ -2600,5 +2622,5 @@ } data; ///< value of metadata char *comment; ///< optional comment ("", not NULL) - psDlist *restrict items; ///< list of psMetadataItems with the same name + psList *restrict items; ///< list of psMetadataItems with the same name } psMetadataItem; \end{verbatim} @@ -2643,5 +2665,5 @@ \begin{verbatim} typedef struct { - psDlist *restrict list; ///< list of psMetadataItem + psList *restrict list; ///< list of psMetadataItem psHash *restrict table; ///< hash table of the same metadata } psMetadata; @@ -3119,5 +3141,5 @@ const int nx, ny; ///< Image binning psImage *image; ///< imaging area of cell - psDlist *objects; ///< objects derived from cell + psList *objects; ///< objects derived from cell psMetadata *md; ///< Readout-level metadata } psReadout;