Changeset 792 for trunk/doc/pslib/psLibSDRS.tex

Timestamp:

May 26, 2004, 4:34:32 PM (22 years ago)

Author:

eugene

Message:

minor edits from several recent bugs (~29-39)

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (8 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $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 +212 @@
 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 +223 @@
 \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 +240 @@
 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 +250 @@
 \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 +390 @@
 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 +2106 @@
 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 +2131 @@
 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}