\chapter{Area Detector API Reference}
\label{ch:areadetectorapi}

\section{Area Detector Definitions}

\subsection{Area Detector Status Word}
\label{subsec:statusbits}

The current status of the area detector can be determined by calling
either the \mxfn{mx\_area\_detector\_get\_status()} function or the
\mxfn{mx\_area\_detector\_get\_extended\_status()} function, both of which
return a 32-bit status word.
Currently the following bits are defined:
\begin{description}
  \item[MXSF\_AD\_ACQUISITION\_IN\_PROGRESS (0x1)]\ \newline
  	This status bit is set if the detector is currently recording
	a sequence of image frames.
	For most sequence types,
	the \textit{Acquisition In Progress} bit will turn off
	after the last frame has been acquired.  However, for Continuous
	mode, the \textit{Acquisition In Progress} bit will
	continue to be set until the imaging sequence is explicitly
	stopped or aborted.
  \item[MXSF\_AD\_CORRECTION\_IN\_PROGRESS (0x2)]\ \newline
  	This bit is set if the frame in the primary frame buffer is
	currently undergoing image correction.  This bit refers to
	what are sometimes called \textit{online corrections}.
	\textbf{Warning:}  This bit is not yet implemented.  It will
	be implemented when geometrical corrections have been added
	to the area detector software.
  \item[MXSF\_AD\_CORRECTION\_MEASUREMENT\_IN\_PROGRESS (0x4)]\ \newline
  	This bit is set if a dark current or flood field correction
	frame imaging sequence is currently in progress.  This bit will
	only be set if the \textit{mxserver} command line includes the
	\textit{`-c'} flag which turns on event callback mode.
\end{description}

\subsection{Frame Buffer Types}
\label{subsec:framebuffertypes}

The MX area detector record makes provision for several different
frame buffers that are used both for image transfer and image correction
operations.  These buffers are normally identified using individual bits
in a hexadecimal bitmask.  The currently defined frame buffers are
\begin{description}
  \item[MXFT\_AD\_IMAGE\_FRAME (0x0)]\ \newline
  	This is the primary frame buffer that image frames are initially
	read into from the area detector hardware.
  \item[MXFT\_AD\_MASK\_FRAME (0x1)]\ \newline
  	The mask frame is optionally used to ignore masked off pixels
	during the flood field average intensity calculation.
  \item[MXFT\_AD\_BIAS\_FRAME (0x2)]\ \newline
  	CCD detectors typically add a bias offset to pixels returned
	by the area detector hardware to raise the values above the noise
	floor and to reduce the likelihood that dark current subtraction
	will produce a negative value.  The bias frame is optionally
	used to subtract the bias from the frame during image correction.
	The bias is exposure time independent.
  \item[MXFT\_AD\_DARK\_CURRENT\_FRAME (0x4)]\ \newline
  	The dark current frame is optionally used to subtract an exposure time
	dependent dark current from the image frame.  
	Normally, the dark current frame should be taken with
	no photons hitting the imaging surface.
	Depending on the setting of 
	\mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag()},
	the dark current frame will either be scaled
	to match the image frame exposure time, or else the dark current
	frame will be subtracted as is without any scaling.
  \item[MXFT\_AD\_FLOOD\_FIELD\_FRAME (0x8)]\ \newline
  	The flood field frame is optionally used to perform a flood field
	(also known as flat field) correction to the image frame.
%
	Generally, different pixels in an area detector will return slightly
	different signals for the same number of incident photons.
	This can be thought of as a variation in gain for different pixels.
	The flood field frame, if configured, is used to correct for
	this variation in gain.
%
	Ideally, the flood field frame should be taken with
	a uniform photon intensity across the entire imaging surface.
\end{description}
%
Internally, there is an additional image frame buffer, namely the
ROI (Region of Interest)
frame buffer.  In general, this buffer is a different size than the
other buffers above and it does not take part in image correction
or normal image and file I/O.  Instead, there are special ROI-specific
functions that operate on the ROI frame buffer.  In addition, although
the MX area detector class supports multiple ROIs, the ROI frame buffer
itself only contains the contents of one ROI at a time.

\section{mx\_area\_detector\_abort}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_abort}
    	- immediately stop all area detector activity
%
  \mxsynopsis
    mx\_status\_type \mxfn{mx\_area\_detector\_abort}\ ( MX\_RECORD *record );
%
  \mxdescription
    This function tells the area detector to abort all current operations
    such as image acquisition as quickly as possible.  If an imaging
    sequence is currently in progress, the current image frame may be lost.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_stop()}
  }
%
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_arm}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_arm}
    	- prepare the area detector for image acquisition
%
  \mxsynopsis
    mx\_status\_type \mxfn{mx\_area\_detector\_arm}\ ( MX\_RECORD *record );
%
  \mxdescription
    This function tells the area detector to perform all operations needed
    to get ready to be triggered for an imaging sequence.  If the area
    detector has been set by
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
    to a triggering mode that requires an external trigger, the imaging
    sequence will start when the first external trigger pulse arrives.

    If the area detector is in an internal triggering mode, then
    the program must invoke
    \mxfn{mx\_area\_detector\_trigger()}
    to start the imaging sequence.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()},
    \mxfn{mx\_area\_detector\_trigger()}
  }
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_copy\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_copy\_frame}
    	- copy a frame on the area detector computer
%
  \mxsynopsis
    mx\_status\_type \mxfn{mx\_area\_detector\_copy\_frame}\ (
    		\begin{tabular}[t]{@{}l}
    			MX\_RECORD *record, \\
			long source\_frame\_type,\\
			long destination\_frame\_type); \\
		\end{tabular}
%
  \mxdescription
    This function copies a frame on the area detector control computer from one
    of the predefined frame buffers to another of the predefined frame buffers.
    The arguments \mxarg{source\_frame\_type} and
    \mxarg{destination\_frame\_type} are long integers
    that refer to the buffers.  The list of available frame buffers
    can be found in Section~\ref{subsec:framebuffertypes}
%
%    \input ads_frame_buffer_types
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_correct\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_correct\_frame}
    	- tell the detector computer to perform image correction
%
  \mxsynopsis
    mx\_status\_type 
    \mxfn{mx\_area\_detector\_correct\_frame}\ ( MX\_RECORD *record );
%
  \mxdescription
    This function tells the detector computer to perform all image corrections
    that are currently enabled.  At present, the types of corrections
    available are \textit{mask correction}, \textit{bias correction},
    \textit{dark current correction}, and \textit{flood field correction}.

    There are two things that must be true for a given correction to be
    performed:
    \begin{itemize}
      \item The correction frame must have been loaded into the appropriate
      buffer on the detector computer.  This can either be done automatically
      at program startup time or manually by a later call to 
      \mxfn{mx\_load\_frame()}.
      %
      \item The bit in the correction flags bitmask for this correction
      must have been set either at program startup time or by a call to
      \mxfn{mx\_set\_correction\_flags()}.
    \end{itemize}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_load\_frame()},
    \mxfn{mx\_area\_detector\_set\_correction\_flags()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_binsize}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_binsize}
    	- reports the current x and y image binning
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_binsize}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long *x\_binsize,   \\
			long *y\_binsize ); \\
		\end{tabular}
%
  \mxdescription
    This function reports the scale factors for image frame binning
    in the detector.
    For example, if the \textit{x} binsize is 2, then the values of
    pairs of adjacent pixels in the X direction will added together
    and returned as one pixel value.  If both the \textit{x} and
    \textit{y} binsizes are set to 2, then a two by two square of four pixels
    will be added together and returned as one pixel.
    If the detector is in unbinned mode, the binsizes reported will be 1.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_binsize()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_bits\_per\_pixel}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_bits\_per\_pixel}
    	- reports the number of significant bits in a single image pixel
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_bits\_per\_pixel}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *bits\_per\_pixel ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the number of significant bits in a single
    image pixel for the current image format.  Typically, this number
    reflects the resolution of the ADCs in the detector.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_bytes\_per\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_bytes\_per\_frame}
    	- reports the number of bytes in a single image frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_bytes\_per\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *bytes\_per\_frame ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the number of bytes in a single image frame
    for the current image format, framesize, and binning.  This size
    does not include the size of the image header (if present).
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_bytes\_per\_pixel}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_bytes\_per\_pixel}
    	- reports the number of bytes per pixel in the current image format
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_bytes\_per\_pixel}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double *bytes\_per\_pixel ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the number of bytes in a single image pixel
    for the current image format.  \textit{Bytes\_per\_pixel} is returned
    as a \textit{double} due to the fact that there exist image formats
    for which the number of bytes per pixel is not an integer.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_correction\_flags}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_correction\_flags}
    	- reports a bitmask listing the currently enabled image corrections
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_correction\_flags}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					unsigned long *correction\_flags ); \\
				\end{tabular}
%
  \mxdescription
    This function returns a bitmask that describes the set of image
    corrections that are currently enabled.  A given correction is enabled
    if the bit for that correction in the bitmask has a value of 1.
    A description of the bitmask for the available corrections can be found
    in the description for the \mxfn{mx\_area\_detector\_copy\_frame()}
    function.  Please note that the MXFT\_AD\_IMAGE\_FRAME (0x1) bit is
    ignored in this context.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_copy\_frame()},
    \mxfn{mx\_area\_detector\_set\_correction\_flags()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_detector\_readout\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time}
    	- reports the detector readout time for the current mode.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double *detector\_readout\_time ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the amount of time in seconds that is required
    to readout all of the pixels in a detector image frame in the 
    current detector mode.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_extended\_status}
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_extended\_status}
    	- reports the last frame number, the total number of frames,
	and the status flags for an area detector.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_extended\_status}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *last\_frame\_number, \\
					long *total\_num\_frames, \\
					unsigned long *status\_flags ); \\
				\end{tabular}
%
  \mxdescription
    This function returns the last area detector frame number
    just like \mxfn{mx\_area\_detector\_get\_last\_frame\_number()},
    the total number of frames acquired since program start just like
    \mxfn{mx\_area\_detector\_get\_total\_num\_frames()},
    and the area detector status flags just like
    \mxfn{mx\_area\_detector\_get\_status()}.
    See the descriptions of these three functions for
    a more detailed description of what they return.
    
    If the application program
    is polling for these values across an MX network connection, then
    this function will be more efficient than three separate calls to
    the other three functions, since only one network transaction will
    take place.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number()},
    \mxfn{mx\_area\_detector\_get\_total\_num\_frames()},
    \mxfn{mx\_area\_detector\_get\_status()}
  }
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_frame}
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_frame}
    	- returns the requested image frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long frame\_number, \\
					MX\_IMAGE\_FRAME **frame ); \\
				\end{tabular}
%
  \mxdescription
    This is a utility function that returns an MX\_IMAGE\_FRAME structure
    that contains the image corresponding to the requested
    \textit{frame\_number}.  If \textit{frame\_number} has the value -1,
    then the most recently acquired frame will be returned.
%
    This function consolidates a sequence of calls to the functions
    \mxfn{mx\_area\_detector\_setup\_frame()},
    \mxfn{mx\_area\_detector\_readout\_frame()},
    \mxfn{mx\_area\_detector\_correct\_frame()}, and
    \newline
    \mxfn{mx\_area\_detector\_transfer\_frame()}
    into one call.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_setup\_frame()},
    \mxfn{mx\_area\_detector\_readout\_frame()},
    \mxfn{mx\_area\_detector\_correct\_frame()},
    \mxfn{mx\_area\_detector\_transfer\_frame()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_framesize}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_framesize}
    	- reports the current x and y image frame size
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_framesize}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long *x\_framesize,   \\
			long *y\_framesize ); \\
		\end{tabular}
%
  \mxdescription
    This function reports the current resolution of image frames in the
    area detector taking binning into account.  If currently the
    maximum frame size is 4096 by 4096 with 2 by 2 binning, then
    \mxfn{mx\_area\_detector\_get\_framesize()} will report a frame size
    of 2048 by 2048.
    If the detector is in unbinned mode, the frame size reported will be
    the same as that reported by
    \mxfn{mx\_area\_detector\_get\_maximum\_framesize()}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_binsize()},
    \mxfn{mx\_area\_detector\_get\_maximum\_framesize()}
    \mxfn{mx\_area\_detector\_set\_framesize()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_image\_format}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_image\_format}
    	- reports the current image format
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_image\_format}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long *image\_format ); \\
		\end{tabular}
%
  \mxdescription
    This function returns the detector image format as a numerical value.
    The list of supported formats can be found in
    Section~\ref{subsec:imageformats}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_image\_format()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_last\_frame\_number}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number}
    	- reports the most recently acquired frame number
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *last\_frame\_number ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the frame number for the most recently acquired
    image frame.  It is also the highest frame number for which a call to
    \mxfn{mx\_area\_detector\_readout\_frame()} or
    \mxfn{mx\_area\_detector\_get\_frame()} will return valid data,
    if the current sequence is not a circular sequence.
    If the area detector has not yet finished taking the first frame
    in a new sequence, the value reported for \textit{last\_frame\_number}
    will be -1.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_extended\_status()},
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_maximum\_frame\_number}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_maximum\_frame\_number}
    	- reports the maximum frame number that is currently possible
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_maximum\_frame\_number}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *maximum\_frame\_number ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the maximum allowed frame number for the
    current configuration of the area detector.
    In other words, \mxfn{mx\_area\_detector\_get\_last\_frame\_number()}
    will never return a value larger than the maximum allowed frame number.
    Changing the detector
    framesize, binsize, or sequence parameters can change the value 
    returned by this function.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_maximum\_framesize}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_maximum\_framesize}
    	- reports the maximum possible x and y image frame size
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_maximum\_framesize}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long *maximum\_x\_framesize,   \\
			long *maximum\_y\_framesize ); \\
		\end{tabular}
%
  \mxdescription
    This function reports the maximum possible image frame size 
    for the area detector.  If the area detector is currently in
    unbinned mode (binsize = 1), 
    \mxfn{mx\_area\_detector\_get\_framesize()} will report
    the same value.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_binsize()},
    \mxfn{mx\_area\_detector\_get\_framesize()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_register}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_register}
    	- returns the value of the requested detector register
	as a long integer
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_register}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_RECORD *record, \\
				char *register\_name, \\
				long *register\_value ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the value
    of the requested detector register as a long integer.
    If the register value is not representable as long integer,
    then the function returns an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_register()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_roi}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_roi}
    	- returns the boundaries of the requested region of interest
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_roi}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_RECORD *record, \\
				unsigned long roi\_number, \\
				unsigned long *roi ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the boundaries of the region of interest (ROI)
    specified by \textit{roi\_number}.  The boundaries of the ROI
    are expressed in binned coordinates.  The data in the boundary rows
    and columns is considered to be part of the ROI.

    The \textit{roi} array argument is an array of four unsigned longs
    with the boundaries stored in the order
    $X_{min}$, $X_{max}$, $Y_{min}$ and $Y_{max}$.
    Here is an example of using this function:
\begin{verbatim}
    ...
    MX_RECORD *ad_record;
    unsigned long roi_number;
    unsigned long roi[4];
    ...
    roi_number = 5;

    mx_status = mx_area_detector_get_roi( ad_record, roi_number, roi );

    if ( mx_status.code != MXE_SUCCESS )
        return mx_status;

    fprintf(stderr,
        "ROI(%lu) = Xmin = %lu, Xmax = %lu, Ymin = %lu, Ymax = %lu\n",
                roi_number, roi[0], roi[1], roi[2], roi[3] );
    ...
\end{verbatim}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_roi()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_roi\_frame}
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_roi\_frame}
    	- returns the requested ROI as an image frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_roi\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					MX\_IMAGE\_FRAME *frame ); \\
					unsigned long roi\_number, \\
					MX\_IMAGE\_FRAME **roi\_frame ); \\
				\end{tabular}
%
  \mxdescription
    This returns an MX\_IMAGE\_FRAME structure
    that contains the contents of the region of interest (ROI)
    corresponding to the requested \textit{roi\_number}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_roi()},
    \mxfn{mx\_area\_detector\_set\_roi()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_sequence}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_sequence}
    	- reads all image frame in a sequence
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_sequence}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long num\_frames, \\
					MX\_IMAGE\_SEQUENCE **sequence); \\
				\end{tabular}
%
  \mxdescription
    Reads out all of the frames in an MX\_IMAGE\_SEQUENCE.
    The images are read out by a series of calls to
    \mxfn{mx\_area\_detector\_get\_sequence()}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_frame()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_sequence\_parameters}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_sequence\_parameters}
    	- reports the current imaging sequence type
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_sequence\_parameters}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
		\kern-55pt\ MX\_SEQUENCE\_PARAMETERS *sequence\_parameters ); \\
		\end{tabular}
%
  \mxdescription
    This function reports the imaging sequence parameters that
    are currently configured for
    the area detector in an MX\_SEQUENCE\_PARAMETERS structure.
    The MX\_SEQUENCE\_PARAMETERS structure is defined as follows:

\begin{verbatim}
typedef struct {
        long sequence_type;
        long num_parameters;
        double parameter_array[MXU_MAX_SEQUENCE_PARAMETERS];
} MX_SEQUENCE_PARAMETERS;
\end{verbatim}

    The \textit{sequence\_type} member specifies which type of sequence
    has been requested using the sequence type definitions near the top
    of the \mxfn{\$MXDIR/include/mx\_image.h} header file.
    The \textit{num\_parameters} and the
    \textit{parameter\_array} members provide sequence type specific
    information for the sequence in question.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_sequence\_start\_delay}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_sequence\_start\_delay}
    	- reports the sequence start delay time.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_sequence\_start\_delay}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			double *sequence\_start\_delay ); \\
		\end{tabular}
%
  \mxdescription
    For some area detectors, the detector can be configured to wait
    for a specified delay time before starting the
    data acquisition sequence.  This function reports the value
    of the delay time in seconds.  Area detectors that do not support
    this feature will return a delay time of 0.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time()},
    \mxfn{mx\_area\_detector\_get\_total\_acquisition\_time()},
    \mxfn{mx\_area\_detector\_get\_total\_sequence\_time()},
    \mxfn{mx\_area\_detector\_set\_sequence\_start\_delay()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_status}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_status}
    	- gets the area detector status flags
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_status}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					unsigned long status\_flags ); \\
				\end{tabular}
%
  \mxdescription
    Returns a bitmap of status flags where the individual flag bits represent
    different aspects of the current status of the area detector.  
    The currently defined status flags are described in
    Section~\ref{subsec:statusbits}.

    At present, the only status flag defined is MXSF\_AD\_IS\_BUSY.
    It is anticipated that this will expand to include status flags
    for internal software or hardware faults of the detector system.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_extended\_status()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_total\_acquisition\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_total\_acquisition\_time}
    	- reports the time required to acquire the image frames 
	for the current mode.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_total\_acquisition\_time}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double *total\_acquisition\_time ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the amount of time in seconds that is required
    to acquire all of the image frames for the current sequence.
    In general, it does not include detector readout times
    or the gap time between exposures.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time()},
    \mxfn{mx\_area\_detector\_get\_sequence\_start\_delay()},
    \mxfn{mx\_area\_detector\_get\_total\_sequence\_time()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_total\_num\_frames}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number}
    	- reports the total number of image frame acquired.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_total\_num\_frames}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long *total\_num\_frames ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the total number of image frames acquired
    since program startup time.
    If the area detector has not yet finished taking the first frame
    in a new sequence, the value reported for \textit{total\_num\_frames}
    will be 0.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_extended\_status()},
    \mxfn{mx\_area\_detector\_get\_last\_frame\_number()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_total\_sequence\_time}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_total\_sequence\_time}
    	- reports the total sequence time for the current mode.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_total\_sequence\_time}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double *total\_sequence\_time ); \\
				\end{tabular}
%
  \mxdescription
    This function reports the amount of time in seconds that is required
    for the detector to run the currently configured sequence.

    \textbf{Warning:} The total sequence time reported does not include
    the correction time, the time required to transfer
    the frames across the network, or the time required to write the
    frames to disk.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time()},
    \mxfn{mx\_area\_detector\_get\_sequence\_start\_delay()},
    \mxfn{mx\_area\_detector\_get\_total\_acquisition\_time()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_trigger\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_trigger\_mode}
    	- reports the internal/external trigger mode for the detector
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_trigger\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long *trigger\_mode ); \\
		\end{tabular}
%
  \mxdescription
    This function is used to report whether or not the area detector is in
    internal (0x1) or external trigger (0x2) mode.  
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_get\_use\_scaled\_dark\_current\_flag}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_get\_use\_scaled\_dark\_current\_flag}
    	- returns the use\_scaled\_dark\_current flag
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_get\_use\_scaled\_dark\_current\_flag}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
		\kern-15pt\ mx\_bool\_type *use\_scaled\_dark\_current ); \\
		\end{tabular}
%
  \mxdescription
    This function returns the 
    \textit{use\_scaled\_dark\_current} flag for the area detector.
%
    If the \textit{use\_scaled\_dark\_current} flag is set in the detector
    computer, dark current subtraction will be done using dark current
    values that have been rescaled to the actual exposure time of the image.
    If the \textit{use\_scaled\_dark\_current} flag is \textit{not} set,
    then raw unscaled dark current values will be subtracted instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_is\_busy}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_is\_busy}
  - reports whether or not the area detector is acquiring an image sequence,
    correcting a frame, or making a correction frame measurement.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_is\_busy}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					mx\_bool\_type *busy ); \\
				\end{tabular}
%
  \mxdescription
    This is a utility function that reports whether or not the area
    detector is currently acquiring images for an image sequence.
    \mxfn{mx\_area\_detector\_is\_busy()}\ returns TRUE if
    any of the status bits 
    \begin{enumerate}
    \item[] MXSF\_AD\_ACQUISITION\_IN\_PROGRESS (0x1),
    \item[] MXSF\_AD\_CORRECTION\_IN\_PROGRESS (0x2), or
    \item[] MXSF\_AD\_CORRECTION\_MEASUREMENT\_IN\_PROGRESS (0x4)
    \end{enumerate}
    are set.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_status()},
    \mxfn{mx\_area\_detector\_get\_extended\_status()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_load\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_load\_frame}
    - load an image frame into the requested image buffer
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_load\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long frame\_type, \\
					char *frame\_filename ); \\
				\end{tabular}
%
  \mxdescription
    This function loads an image frame into a frame buffer on the
    detector computer specified by \textit{frame\_type} from
    the file on the detector computer specified by \textit{frame\_filename}.
%
    This function is intended to be used for loading mask, bias,
    dark current, and flood field image frames on the detector computer.
%
    The image format for the file must match the image format of the
    detector computer's area detector record.  If it does not, the load
    will fail.  The allowed values of the \textit{frame\_type} argument
    can be found in the description of the
    \mxfn{mx\_area\_detector\_copy\_frame()} function.

    If you want to load an image frame into a user application program,
    then you should be using the function
    \mxfn{mx\_image\_read\_file()} instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_copy\_frame()},
    \mxfn{mx\_area\_detector\_save\_frame()},
    \mxfn{mx\_image\_read\_file()},
    \mxfn{mx\_image\_write\_file()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_measure\_correction\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_measure\_correction\_frame}
    - perform a series of measurements to construct a correction frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_measure\_correction\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long correction\_measurement\_type, \\
					double correction\_measurement\_time, \\
					long num\_correction\_measurements ); \\
				\end{tabular}
%
  \mxdescription
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()} is used 
    to generate the data with which to construct either a dark current
    correction frame or a flood field correction frame.  The
    \textit{correction\_measurement\_type}\ is one of the two values
    MXFT\_AD\_DARK\_CURRENT\_FRAME or MXFT\_AD\_FLOOD\_FIELD\_FRAME
    as described in Section~\ref{subsec:framebuffertypes}.
    The correction frame is measured by taking the average of
    \textit{num\_correction\_measurements}\ worth of detector images
    for an exposure time per frame of \textit{correction\_measurement\_time}.

    In general, the dark current frame should be measured without any
    radiation hitting the detector, while the flood field frame should
    be measured with a uniform source of radiation hitting the detector.

    Since the absolute intensity of the dark current frame is normally
    a function of the exposure time, you can choose to either rescale
    the dark current intensity to the actual exposure time or else
    subtract the unscaled dark current value.  The choice of
    mode can be made using 
    \mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag()}.

    There are also a pair of convenience macros called
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame()} and
    \mxfn{mx\_area\_detector\_measure\_flood\_field\_frame()} which call
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()}
    to do the real work.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame()},
    \mxfn{mx\_area\_detector\_measure\_flood\_field\_frame()},
    \mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_measure\_dark\_current\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame}
    - perform a series of measurements to construct a dark current frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double correction\_measurement\_time, \\
					long num\_correction\_measurements ); \\
				\end{tabular}
%
  \mxdescription
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame()} invokes
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()} with
    the \textit{correction\_measurement\_type} set to
    MXFT\_AD\_DARK\_CURRENT\_FRAME.  See the description of
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()}
    for more information.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()},
    \mxfn{mx\_area\_detector\_measure\_flood\_field\_frame()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_measure\_flood\_field\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_measure\_flood\_field\_frame}
    - perform a series of measurements to construct a flood field frame
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					double correction\_measurement\_time, \\
					long num\_correction\_measurements ); \\
				\end{tabular}
%
  \mxdescription
    \mxfn{mx\_area\_detector\_measure\_flood\_field\_frame()} invokes
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()}\newline
    with the \textit{correction\_measurement\_type} set to 
    MXFT\_AD\_FLOOD\_FIELD\_FRAME.  See the description of\newline
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()}
    for more information.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_measure\_correction\_frame()},
    \mxfn{mx\_area\_detector\_measure\_dark\_current\_frame()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_readout\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_readout\_frame}
    - read a frame into the primary image buffer
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_readout\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long frame\_number ); \\
				\end{tabular}
%
  \mxdescription
    This function reads the requested image frame from the 
    area detector hardware
    into the primary image buffer of the detector computer.
    If the requested frame number is -1, the most recently acquired
    image will be read out.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_save\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_save\_frame}
    - save a frame from the requested image buffer to a file
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_save\_frame}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					long frame\_type, \\
					char *frame\_filename ); \\
				\end{tabular}
%
  \mxdescription
    This function saves an image frame from the frame buffer on the
    detector computer specified by \textit{frame\_type} to
    the file on the detector computer specified by \textit{frame\_filename}.
%
    This function is primarily intended to be used for saving the
    most recently acquired image frame to a disk file on the
    detector computer.  However, it save frames from any of the
    image buffers listed in the description of the
    \mxfn{mx\_area\_detector\_copy\_frame()} function.
%
    The image file will be written using the current image format
    of the area detector.

    If you want a user application program to save an image frame to disk,
    then you should be using the function
    \mxfn{mx\_image\_write\_file()} instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_copy\_frame()},
    \mxfn{mx\_area\_detector\_load\_frame()},
    \mxfn{mx\_image\_read\_file()},
    \mxfn{mx\_image\_write\_file()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_binsize}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_binsize}
    	- set the current x and y image binning factors
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_binsize}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long x\_binsize,   \\
			long y\_binsize ); \\
		\end{tabular}
%
  \mxdescription
    This function sets the scale factor for image frame binning
    in the detector.
    For example, if the \textit{x} binsize is 2, then the values of
    pairs of adjacent pixels in the X direction will added together
    and returned as one pixel value.  If both the \textit{x} and
    \textit{y} binsizes are set to 2, then a two by two square of four pixels
    will be added together and returned as one pixel.
    If you want to put the detector into unbinned mode,
    then set both binsizes to 1.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_binsize()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_bulb\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_bulb\_mode}
    	- change the area detector to use Bulb mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_bulb\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_frames ); \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a \textit{Bulb mode}
    image sequence.  In Bulb mode, the area detector uses the
    current state of an external trigger signal to determine when the
    exposure for the current frame should start and end.  In other words,
    in Bulb mode the area detector will expose the current frame for
    as long as the external trigger input is set to high.  When the 
    external trigger input goes to the low state, the exposure for the current
    frame ends.  The next frame does not start until the external trigger
    input goes high again.
    The area detector stops taking frames once the number of frames
    specified by the \textit{num\_frames} argument have been taken.

    If the area detector has not been configured by
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()} to use an external trigger
    at the time that the next image sequence is started, the attempt
    to start the sequence will fail with an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_circular\_multiframe\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode} -
      \parbox[t]{8.0cm}{
        change the area detector to use 
	Circular Multiframe mode image sequences
      }
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_frames, \\
			double exposure\_time, \\
			double frame\_time ); \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a 
    \textit{Circular Multiframe mode} image sequence.
    Circular Multiframe mode sequences are similar
    to Multiframe mode sequences as described by the documentation for
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()}.
    The primary difference is that after a frame has been read
    into the last of the area detector's internal image buffers,
    the sequence goes back to the beginning to overwrite the first 
    image buffer.

    For example, suppose that 
    \mxfn{mx\_area\_detector\_get\_maximum\_frame\_number()}
    reports that the area detector has 25 internal frame buffers.
    If you start a Multiframe sequence, you can acquire at most
    25 frames.  However, suppose you start a Circular Multiframe
    sequence with 40 frames requested.  In this case, the first
    25 frames of will be written to internal frame buffers 0 to 24.
    The last 15 frames will then go back and overwrite internal
    frame buffers 0 to 14.  If your client program is able to read
    out frames faster than the server acquires them, then you can
    read out an indefinitely large number of frames.

    You must be careful to choose the time between the start of
    frames (called the \textit{frame\_time}), so that frames are read
    out before they are overwritten by later frames.  Detectors
    like the Aviex PCCD-170170 detector are definitely capable
    of acquiring frames faster than they can be read out,
    so this is a real issue.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_abort()},
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()},
    \mxfn{mx\_area\_detector\_stop()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_continuous\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_continuous\_mode}
    	- change the area detector to use Continuous mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_continuous\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			double exposure\_time ) \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a 
    \textit{Continuous mode} image sequence.  In Continuous mode,
    the area detector repeatedly takes image frames that all have the
    same duration as requested by the \textit{exposure\_time} argument
    in seconds.  Each new frame overwrites the previous one.
    The detector will continue taking frames until explicitly
    stopped or aborted.
    It is anticipated that this mode will be mostly useful for
    diagnostic applications that want a continuously updated GUI display
    of images acquired by the detector.

    Continuous mode can be used with either an internal trigger
    or an external trigger.  If a strobed external trigger mode 
    been requested by \mxfn{mx\_area\_detector\_set\_trigger\_mode()},
    the detector will take a new frame for each external trigger pulse
    received by the detector.  If a non-strobed external trigger mode
    has been selected, the detector will merely use the first external
    trigger received to start the sequence and ignore all subsequent
    triggers.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_abort()},
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()},
    \mxfn{mx\_area\_detector\_stop()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_correction\_flags}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_correction\_flags}
    	- specifies which image corrections are to be performed.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_correction\_flags}\ (
    				\begin{tabular}[t]{@{}l}
					MX\_RECORD *record, \\
					unsigned long correction\_flags ); \\
				\end{tabular}
%
  \mxdescription
    The \textit{correction\_flags} argument for this function is
    a bitmask that describes the set of image
    corrections to be enabled.  A given correction is enabled
    if the bit for that correction in the bitmask has a value of 1.
    A description of the bitmask for the available corrections can be found
    in the description for the \mxfn{mx\_area\_detector\_copy\_frame()}
    function.  Please note that the MXFT\_AD\_IMAGE\_FRAME (0x1) bit has
    no meaning in this context.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_copy\_frame()},
    \mxfn{mx\_area\_detector\_get\_correction\_flags()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_framesize}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_framesize}
    	- sets the current x and y image frame size
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_framesize}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long x\_framesize,   \\
			long y\_framesize ); \\
		\end{tabular}
%
  \mxdescription
    For some detectors, this function sets the current resolution
    of image frames in the area detector taking binning into account.  
    Not all detectors support this function.  Some will round the
    requested dimensions to the reported size, while others will
    return an error regardless of the framesize values supplied.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_binsize()},
    \mxfn{mx\_area\_detector\_get\_framesize()},
    \mxfn{mx\_area\_detector\_get\_maximum\_framesize()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_geometrical\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode}
    	- change the area detector to use Geometrical mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_frames, \\
			double exposure\_time, \\
			double frame\_time,\\
			double exposure\_multiplier, \\
			double gap\_multiplier ); \\
		\end{tabular}
%
  \mxdescription
    Geometrical mode sequences are currently only supported by the
    AVIEX PCCD-170170 CCD detector.  Geometrical mode sequences are
    multiframe sequences that take the number of frames requested by
    the \textit{num\_frames} argument.  For the first frame, the duration
    of the exposure time in seconds will be the value requested by the
    \textit{exposure\_time} argument.  The gap in seconds 
    between the first and the second frames will be the \textit{frame\_time}
    minus the \textit{exposure\_time} and the detector readout time.
    For each subsequent frame, the exposure time
    will be the exposure time for the previous frame multiplied by
    the value of the \textit{exposure\_multipler} argument.  Similarly,
    the duration of the gap between frames will be the previous gap time
    multiplied by the value of the \textit{gap\_multiplier} argument.
    This means that the exposure time and the gap time will continue
    to get longer as the sequence progresses.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_image\_format}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_image\_format}
    	- changes the current image format
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_image\_format}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long image\_format ); \\
		\end{tabular}
%
  \mxdescription
    This function sets the detector image format as a numerical value.
    A list of the supported image formats can be found in
    Section~\ref{subsec:imageformats}.
%
  \mxwarning
    Most detectors do not support this function.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_image\_format()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_multiframe\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode}
    	- change the area detector to use Multiframe mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_frames, \\
			double exposure\_time, \\
			double frame\_time ); \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a 
    \textit{Multiframe mode} image sequence.  In Multiframe mode, the
    \textit{exposure\_time} specifies the duration in seconds
    of the exposure for each frame.  In addition,
    the time interval between the start of two consecutive frames
    will be the \textit{frame\_time} in seconds.

    Multiframe mode can be used with either an internal trigger
    or an external trigger.  If an external trigger mode has been configured
    by \mxfn{mx\_area\_detector\_set\_trigger\_mode()}, the sequence
    uses the next pulse from the external trigger to start the imaging
    sequences.  All subsequent trigger pulses are ignored.  The imaging
    sequence will stop once the number of image frames requested by
    the \textit{num\_frames} argument have been taken.

    If you want the sequence to loop by going back to overwrite the
    first frame once the last frame has been acquired, you should use
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()} instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_one\_shot\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode}
    	- change the area detector to use One-shot mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			double exposure\_time ) \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a 
    \textit{One-shot mode} image sequence.  In One-shot mode,
    the area detector takes a single frame that is exposed for
    the duration requested by the \textit{exposure\_time} argument.
    One-shot mode can be used with either an internal trigger
    or an external trigger.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_abort()},
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()},
    \mxfn{mx\_area\_detector\_stop()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_register}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_register}
    	- sets the value of the requested detector register
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_register}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_RECORD *record, \\
				char *register\_name, \\
				long *register\_value ); \\
			\end{tabular}
%
  \mxdescription
    This function sets the named detector register to the value
    specified.  If the register value is not representable
    as long integer, then the function returns an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_register()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_roi}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_roi}
    	- sets the boundaries of the requested region of interest
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_roi}\ (
    			\begin{tabular}[t]{@{}l}
				MX\_RECORD *record, \\
				unsigned long roi\_number, \\
				unsigned long *roi ); \\
			\end{tabular}
%
  \mxdescription
    This function returns the boundaries of the region of interest (ROI)
    specified by \textit{roi\_number}.  The boundaries of the ROI
    are expressed in binned coordinates.  The data in the boundary rows
    and columns is considered to be part of the ROI.

    The \textit{roi} array argument is an array of four unsigned longs
    with the boundaries stored in the order
    $X_{min}$, $X_{max}$, $Y_{min}$ and $Y_{max}$.
    Here is an example of using this function:
\begin{verbatim}
    ...
    MX_RECORD *ad_record;
    unsigned long roi_number;
    unsigned long roi[4];
    ...
    roi_number = 5;

    roi[0] = 1000;    /* X minimum */
    roi[1] = 2000;    /* X maximum */
    roi[2] = 1250;    /* Y minimum */
    roi[3] = 1750;    /* Y maximum */

    mx_status = mx_area_detector_set_roi( ad_record, roi_number, roi );

    if ( mx_status.code != MXE_SUCCESS )
        return mx_status;
    ...
\end{verbatim}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_roi()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_sequence\_parameters}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters}
    	- sets up any of the available types of image sequences.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
		\kern-50pt\ MX\_SEQUENCE\_PARAMETERS *sequence\_parameters ); \\
		\end{tabular}
%
  \mxdescription
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()}\ is the common
    function that underlies all of the other commands for selecting specific
    sequence modes.  The command takes a single argument
    which is a pointer to an
    MX\_SEQUENCE\_PARAMETERS structure.  The MX\_SEQUENCE\_PARAMETERS
    structure is defined as follows:

\begin{verbatim}
typedef struct {
        long sequence_type;
        long num_parameters;
        double parameter_array[MXU_MAX_SEQUENCE_PARAMETERS];
} MX_SEQUENCE_PARAMETERS;
\end{verbatim}

    The \textit{sequence\_type} member specifies which type of sequence
    has been requested.  The \textit{num\_parameters} and the
    \textit{parameter\_array} members provide sequence type specific
    information for the sequence in question.  In general, it is simpler
    to use the higher level sequence specific mode setting functions.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_sequence\_start\_delay}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_sequence\_start\_delay}
    	- changes the sequence start delay time.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_sequence\_start\_delay}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			double sequence\_start\_delay ); \\
		\end{tabular}
%
  \mxdescription
    For some area detectors, the detector can be configured to wait
    for a specified delay time before starting the
    data acquisition sequence.  This function changes the value
    of the delay time in seconds.  Area detectors that do not support
    this feature will return an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_detector\_readout\_time()},
    \mxfn{mx\_area\_detector\_get\_sequence\_start\_delay()}
    \mxfn{mx\_area\_detector\_get\_total\_acquisition\_time()},
    \mxfn{mx\_area\_detector\_get\_total\_sequence\_time()},
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_streak\_camera\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode}
    	- change the area detector to use Streak Camera mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_lines, \\
			double exposure\_time\_per\_line ); \\
		\end{tabular}
%
  \mxdescription
    This is an AVIEX PCCD-170170 detector specific mode.
    In Streak Camera mode, acquires the specified number of image lines
    with the specified exposure time per line.  The number of lines
    in a streak camera image can greatly exceed the normal number of
    lines in a full frame image.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_strobe\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_strobe\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_strobe\_mode}
    	- change the area detector to use Strobe mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_strobe\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_frames, \\
			double exposure\_time ); \\
		\end{tabular}
%
  \mxdescription
    This function configures the area detector to use a \textit{Strobe mode}
    image sequence.  In Strobe mode, the start of each frame in the 
    sequence is triggered by an external trigger signal.
    The exposure time for each frame lasts for the amount of time in seconds
    requested by the \textit{exposure\_time} argument.
    The area detector stops taking frames once the number of frames
    specified by the \textit{num\_frames} argument have been taken.
    If an external trigger signal arrives before the preceding frame has
    finished, the results are undefined and depend on the particular
    area detector hardware in use.
%
    When the next image sequence is started, if the area detector has not
    been configured by \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
    to use an external trigger, the attempt
    to start the sequence will fail with an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_subimage\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_subimage\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_subimage\_mode}
    	- change the area detector to use Subimage mode image sequences
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_subimage\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long num\_lines\_per\_subimage, \\
			long num\_subimages, \\
			double exposure\_time, \\
			double subimage\_time, \\
			double exposure\_multiplier, \\
			double gap\_multiplier );
		\end{tabular}
%
  \mxdescription
    This function, which is specific to the AVIEX PCCD-170170, tells
    the detector hardware to only readout the specified number of image lines
    from the detector centered at the center of the bottom row of CCDs.
    This is repeated for the specified number of subimages.

    In some ways, this mode is similar to the Geometrical mode in that
    the exposure time and gap time are multiplied by exposure and gap
    multipliers for each subimage after the first.  For this mode,
    the \textit{subimage\_time} argument plays the same role for each
    subimage as the \textit{frame\_time} does for the Geometrical mode.
%
  \mxwarning
    The number of lines times the number of subimages must be less than
    or equal to the number of lines in a full frame subimage.
    Column binning is restricted to either 1 or 2 in this mode.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_set\_bulb\_mode()},
    \mxfn{mx\_area\_detector\_set\_circular\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_continuous\_mode()},
    \mxfn{mx\_area\_detector\_set\_geometrical\_mode()},
    \mxfn{mx\_area\_detector\_set\_multiframe\_mode()},
    \mxfn{mx\_area\_detector\_set\_one\_shot\_mode()},
    \mxfn{mx\_area\_detector\_set\_sequence\_parameters()},
    \mxfn{mx\_area\_detector\_set\_streak\_camera\_mode()},
    \mxfn{mx\_area\_detector\_set\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_trigger\_mode}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_trigger\_mode}
    	- sets the internal/external trigger mode for the detector
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_trigger\_mode}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			long trigger\_mode ); \\
		\end{tabular}
%
  \mxdescription
    This function will be used to switch between internal (0x1)
    and external (0x2) trigger mode.  
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_trigger\_mode()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag}
    	- changes the state of the use\_scaled\_dark\_current flag
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_set\_use\_scaled\_dark\_current\_flag}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
		\kern-15pt\ mx\_bool\_type use\_scaled\_dark\_current ); \\
		\end{tabular}
%
  \mxdescription
    This function changes the state of the
    \textit{use\_scaled\_dark\_current} flag for the area detector.
%
    If the flag is set,
    dark current subtraction will be done using dark current
    values that have been rescaled to the actual exposure time of the image.
    If the \textit{use\_scaled\_dark\_current} flag is \textit{not} set,
    then raw unscaled dark current values will be subtracted instead.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_get\_use\_scaled\_dark\_current\_flag}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_setup\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_setup\_frame}
    	- create a new frame or modify the size of an existing one.
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_setup\_frame}\ (
    		\begin{tabular}[t]{@{}l}
			MX\_RECORD *record, \\
			MX\_IMAGE\_FRAME **frame ); \\
		\end{tabular}
%
  \mxdescription
    This function takes a pointer to an MX\_IMAGE\_FRAME pointer as its
    second argument as in this example:
\begin{verbatim}
        ...
        MX_IMAGE_FRAME *frame;
        ...
        mx_status = mx_area_detector_setup_frame( record, &frame );
        ...
\end{verbatim}
    If you assign NULL to the \textit{frame} pointer before invoking
    \mxfn{mx\_area\_detector\_setup\_frame()}, it assumes that you want
    to create a new MX\_IMAGE\_FRAME structure with dimensions that match
    the current configuration of the specified area detector.

    If you assign NULL to the \textit{frame} pointer before invoking
    \mxfn{mx\_area\_detector\_setup\_frame()}, it assumes that you just want
    to verify that the MX\_IMAGE\_FRAME object you are passing contains
    an \textit{image\_data} array that is big enough to hold a new image
    frame read from the detector.  If the array is already big enough, then
    nothing is done to the MX\_IMAGE\_FRAME object.  If the array is not
    big enough, the old array is freed and a new array is allocated to take
    its place.

    The purpose of \mxfn{mx\_area\_detector\_setup\_frame()} is to make it
    easy to always ensure that the image frame object you are using is big
    enough to hold a new frame from the area detector, while minimizing
    the number of memory allocations that have to be performed.

    Please note that framesize, format, and other parameters of the
    MX\_IMAGE\_FRAME are determined by looking at the current configuration
    of the specified area detector record.  If you want to directly specify
    all of these parameters yourself, then the function you want to use is 
    \mxfn{mx\_image\_alloc()}.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_image\_alloc()},
    \mxfn{mx\_image\_free()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_start}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_start}
    	- starts a imaging sequence
%
  \mxsynopsis
    mx\_status\_type
    \mxfn{mx\_area\_detector\_start}\ ( MX\_RECORD *record );
%
  \mxdescription
    This is a utility function that starts an imaging sequence
    by invoking \mxfn{mx\_area\_detector\_arm()} followed by
    \mxfn{mx\_area\_detector\_trigger()}.

%    \textit{\FIXME\ -\ This function probably should not invoke
%    mx\_area\_detector\_trigger() if the area detector is configured
%    for an external trigger.}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_arm()},
    \mxfn{mx\_area\_detector\_trigger()}
  }

\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_stop}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_stop}
    	- stops all area detector activity after the current frame
%
  \mxsynopsis
    mx\_status\_type \mxfn{mx\_area\_detector\_stop}\ ( MX\_RECORD *record );
%
  \mxdescription
    This function tells the area detector to stop any imaging sequence
    in process after the current frame completes.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_abort()}
  }
%
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_transfer\_frame}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_transfer\_frame}
    	- sends an image frame to a user application
%
  \mxsynopsis
    mx\_status\_type 
    \mxfn{mx\_area\_detector\_transfer\_frame}\ (
	    		\begin{tabular}[t]{@{}l}
				MX\_RECORD *record, \\
				long frame\_type, \\
				MX\_IMAGE\_FRAME *destination\_frame );\\
			\end{tabular}
%
  \mxdescription
    This function tells the detector computer to send an image from
    the requested detector frame buffer to the user application.  The
    transferred frame will be saved in the specified
    \textit{destination\_frame} in the user application.
    You must make sure that the \textit{destination\_frame} object
    has been set up in advance
    by a call to either \mxfn{mx\_area\_detector\_setup\_frame()}
    or \mxfn{mx\_image\_alloc()} before invoking this function or else
    it will return an error.
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_setup\_frame()},
    \mxfn{mx\_area\_detector\_readout\_frame()},
    \mxfn{mx\_image\_alloc()}
  }
%
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{mx\_area\_detector\_trigger}
%
\begin{description}
  \mxname
    \mxfn{mx\_area\_detector\_trigger}
    	- sends a internal trigger to the area detector
%
  \mxsynopsis
    mx\_status\_type 
    \mxfn{mx\_area\_detector\_trigger}\ ( MX\_RECORD *record );
%
  \mxdescription
    This function tells the detector computer to send an internal trigger
    to the area detector hardware to start an imaging sequence.

%    \textit{\FIXME\ -\ We have not yet specified what happens if you
%    send an internal trigger when the area detector is configured
%    for an external trigger.}
%
  \mxreturnvalue
    On success, the status code MXE\_SUCCESS is returned.
%
  \mxseealso{
    \mxfn{mx\_area\_detector\_arm()},
    \mxfn{mx\_area\_detector\_start()}
  }
%
\end{description}

