Index: trunk/doc/pslib/psLibSDRS.tex =================================================================== --- trunk/doc/pslib/psLibSDRS.tex (revision 748) +++ trunk/doc/pslib/psLibSDRS.tex (revision 792) @@ -1,3 +1,3 @@ -%%% $Id: psLibSDRS.tex,v 1.47 2004-05-20 08:44:30 eugene Exp $ +%%% $Id: psLibSDRS.tex,v 1.48 2004-05-27 02:34:32 eugene Exp $ \documentclass[panstarrs]{panstarrs} @@ -212,7 +212,7 @@ The first and last elements of this structure are \code{void} pointers called \code{startblock} and \code{endblock}, which are assigned a -special value, \code{PS_MEM_MAGIC}. The segment following the +special value, \code{P_PS_MEMMAGIC}. The segment following the user-memory block consists of a single \code{void} pointer, and is -also assigned the special value of \code{PS_MEM_MAGIC}. This address +also assigned the special value of \code{P_PS_MEMMAGIC}. This address is pointed to by the structure element \code{endpost}. @@ -223,5 +223,5 @@ \code{sizeof(psMemBlock)} bytes with the data of the \code{psMemBlock} structure, and the last \code{sizeof(void)} bytes with -\code{PS_MEM_MAGIC}. It returns to the user the pointer corresponding +\code{P_PS_MEMMAGIC}. It returns to the user the pointer corresponding to the address \code{ADDR + sizeof(psMemBlock)}. If the memory management system reallocates a block of memory, it must also allocate @@ -240,6 +240,6 @@ values, which can be detected by the memory management system. In the second case, hexadecimal dumps of large blocks of memory are easier to -examine if the value of \code{PS_MEM_MAGIC} is chosen to catch the -eye. A traditional value for \code{PS_MEM_MAGIC} is \code{0xdeadbeef} +examine if the value of \code{P_PS_MEMMAGIC} is chosen to catch the +eye. A traditional value for \code{P_PS_MEMMAGIC} is \code{0xdeadbeef} which is also easily recognized in a dump of the memory table. @@ -250,11 +250,11 @@ \begin{verbatim} typedef struct { - const void *startblock; ///< initialised to PS_MEM_MAGIC + const void *startblock; ///< initialised to P_PS_MEMMAGIC const unsigned long id; ///< a unique ID for this allocation const char *file; ///< set from __FILE__ in e.g. p_psAlloc const int lineno; ///< set from __LINE__ in e.g. p_psAlloc int refCounter; ///< how many times pointer is referenced - const void **endpost; ///< initialised to PS_MEM_MAGIC - const void *endblock; ///< initialised to PS_MEM_MAGIC + const void **endpost; ///< initialised to P_PS_MEMMAGIC + const void *endblock; ///< initialised to P_PS_MEMMAGIC } psMemBlock; \end{verbatim} @@ -390,7 +390,7 @@ 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{psMemExhaustedCallbackSet}, -the default callback function immediately returns \code{NULL}, in -which case \code{psAlloc} will call \code{psAbort}. +Until the callback function is set with +\code{psMemExhaustedCallbackSet}, or if this callback is set to NULL, +\code{psAlloc} immediately calls \code{psAbort}. \subsubsubsection{\tt psMemProblemCallback} @@ -2106,26 +2106,23 @@ full image or a subimage to be read. The starting pixel of the region is specified by \code{x,y}, while the dimensions of the requested -region are specified by \code{nx,ny}. A negative value of -1 for -these two parameters specifies the full array of the requested image, -less absolute value of the variable. If the native image is a cube, -the value of z specifies the requested slice of the image. The data -is read from the extension specified by extname (matching the EXTNAME -keyword) or by the extnum value (with 0 representing the PHU, 1 the -first extension, etc). This function must call \code{psError} and -return \code{NULL} if any of the specified parameters are out of range -for the data in the image file, if the specified image file does not -exist, or the image on disk is zero- or one-dimensional. +region are specified by \code{nx,ny}. A negative value for either of +\code{nx} or \code{ny} specifies the size of the region to be read +counting down from the end of the array. In other words, the implied +value of \code{nx} is: +\begin{verbatim} +nx = (nx > 0) ? nx : image.ncols - x + nx; +\end{verbatim} +If the native image is a cube, the value of z specifies the requested +slice of the image. The data is read from the extension specified by +extname (matching the EXTNAME keyword) or by the extnum value (with 0 +representing the PHU, 1 the first extension, etc). This function must +call \code{psError} and return \code{NULL} if any of the specified +parameters are out of range for the data in the image file, if the +specified image file does not exist, or the image on disk is zero- or +one-dimensional. \begin{verbatim} -psImage *psImageFReadSection(psImage *output, int x, int y, int nx, int ny, int z, - const char *extname, int extnum, FILE *f); -\end{verbatim} -Read an image or subimage from file descriptor. The input parameters -and their behavior for this function are identical with those in -\code{psImageReadSection}. - -\begin{verbatim} -psImage *psImageWriteSection(const psImage *input, int x, int y, int z, - const char *extname, int extnum, const char *filename); +int psImageWriteSection(const psImage *input, int x, int y, int z, + const char *extname, int extnum, const char *filename); \end{verbatim} Write an image section to the named file, which may exist. This @@ -2134,11 +2131,12 @@ If the specified extension does not exist, it should be created. If an extension is specified and no PHU exists, a basic PHU should be -created. - -\begin{verbatim} -psImage *psImageFWriteSection(const psImage *input, int x, int y, int z, - const char *extname, int extnum, FILE *f); -\end{verbatim} -Write an image section to file descriptor as above: +created. Care must be taken to interpret x,y,z in the two cases a) +there is already an existing image and b) there is not an existing +image. If the image exists, write the complete psImage data to the +existing image starting at the coordinate x,y,z. If any of these +parameters implies writing pixels outside the existing data area of +the image, return an error (ie, if x + image.nx >= NAXIS1, y + +image.ny >= NAXIS2, or z >= NAXIS3). If the image does not exist, +require x,y,z to be zero. \subsubsection{Image Pixel Manipulations}