\chapter{Using the MX Area Detector API}

\section{Building an MX Client}

Setting up the makefile to build an MX client is quite straightforward.
Here is an example for Linux or Unix:
%
\begin{verbatim}
#
# Use defines like these if you are linking to an installed version of MX.
#
MXDIR = /opt/mx-1.5.0

MX_LIB_DIR     = $(MXDIR)/lib
MX_INCLUDE_DIR = $(MXDIR)/include

#
# Use defines like these if you are linking to a copy of MX in a private
# build directory.
#

#MX_LIB_DIR     = /home/lavender/mxdev/mx-1.5.0/mx/libMx
#MX_INCLUDE_DIR = $(MX_LIB_DIR)

CFLAGS = -g -DOS_LINUX -DDEBUG -Wall -Werror -I$(MX_INCLUDE_DIR)

mx_client: mx_client.o
        gcc -g -o mx_client mx_client.o -L$(MX_LIB_DIR) -lMx

mx_client.o: mx_client.c
        gcc $(CFLAGS) -c mx_client.c

clean:
        -rm *.o mx_client

\end{verbatim}

Here is the same example for Windows using Visual C++ 2005 Express:
%
\begin{verbatim}

# Do not forget that filenames and pathnames supplied to Gnu make
# must _not_ include spaces.  That is the reason for the use of
# progra~1 below rather than "Program Files".
#
MSDEV_DIR = c:\\progra~1\\micros~4

WIN32_LIBS = $(MSDEV_DIR)\\lib\\wsock32.lib $(MSDEV_DIR)\\lib\\winmm.lib \
	$(MSDEV_DIR)\\lib\\advapi32.lib $(MSDEV_DIR)\\lib\\user32.lib \
	$(MSDEV_DIR)\\lib\\gdi32.lib $(MSDEV_DIR)\\lib\\uuid.lib

# Manifests are a feature of Visual C++ 2005.  For earlier versions of
# Visual C++, you can leave out the manifest logic.

MSMANIFEST_TOOL = `echo "$(MSDEV_DIR)\\bin\\mt" | tr \\\\ / `

#
# Use defines like these if you are linking to an installed version of MX.
#
MXDIR = c:\\opt\\mx-1.5.0

MX_LIB_DIR     = $(MXDIR)\\lib
MX_INCLUDE_DIR = $MXDIR\\include

# Use defines like these if you are linking to a copy of MX in a private
# build directory.

#MX_LIB_DIR     = c:\\docume~1\\lavender\\mxdev\\mx-1.5.0\\mx\\libMx
#MX_INCLUDE_DIR = $(MX_LIB_DIR)

CFLAGS = -DOS_WIN32 -DDEBUG -nologo -Zi -WX -I$(MX_INCLUDE_DIR)

mx_client.exe: mx_client.obj
        link /debug /nologo /out:mx_client.exe mx_client.obj \
                /nodefaultlib:libc $(MX_LIB_DIR)\\libMx.lib $(WIN32_LIBS)
        $(MSMANIFEST_TOOL) -nologo -outputresource:mx_client.exe\;1 \
                -manifest mx_client.exe.manifest
        rm -f mx_client.exe.manifest

mx_client.obj: mx_client.c
        cl $(CFLAGS) -c mx_client.c

clean:
        -rm *.o mx_client

\end{verbatim}

\section{Initializing MX}

\subsection{mx\_setup\_database()}

Most MX client programs should start by calling an MX utility function
called \myfunction{mx\_setup\_database()}.  Calling it looks like this:
%
\begin{verbatim}
    ...

    MX_RECORD *mx_database;
    char mx_database_filename[] = "/opt/mx/etc/motor.dat";
    mx_status_type mx_status;

    mx_status = mx_setup_database( &mx_database, mx_database_filename );

    if ( mx_status.code != MXE_SUCCESS )
            return mx_status;
    ...
\end{verbatim}
%
\myfunction{mx\_setup\_database()} encapsulates all of the operations required
to use a database file to initialize a running MX database in your
client or server process.  Once \myfunction{mx\_setup\_database()} has
returned successfully, you can be sure that you have successfully connected
to the remote server(s) and your runtime database is ready to be used.

This example demonstrates two MX data types that you will encounter 
all of the time in MX programming.  The first data type is the
\mymxrecord\ structure.
\mymxrecord{}s are the most important object type in MX
and for the most part have a 1 to 1 relationship to the actual hardware
being controlled by the experiment.  Thus, an area detector will have
an \mymxrecord\ that represents it, and the imaging board
that the area detector communicates with will have an
\mymxrecord\ that represents it, and so forth.

The \mymxrecord\ structure is designed to be use as a mostly opaque type.
The only member of it that you are likely to use is the \myds{name} value.
For example, you could print out the name of the \myvar{mx\_database}
record in the example above with code like this:
%
\begin{verbatim}
    ...

    printf("The name of the MX database record is '%s'.\n", mx_database->name);

    ...
\end{verbatim}
%
The output of this line should look like this:
%
\begin{verbatim}
    The name of the MX database record is 'mx_database'.
\end{verbatim}
%
The MX in-memory database is maintained as a circular linked list of
\mymxrecord\ structures.  The \mymxrecord\ returned by 
\myfunction{mx\_setup\_database()} is referred to as the ``list head''
record and is always named ``mx\_database''.  The list head record
maintains information about the MX database as a whole.

The \mymxrecord\ data type is defined near the top of the header file
\myfilename{\$MXDIR/include/mx\_record.h}.  Do not be alarmed by the 
complexity of the data structure you find there.  You should not have to
know about any of it unless you plan to write your own new MX drivers.

The other important data type is the \mymxstatustype.
Most, but not all, MX functions have an \mymxstatustype\ structure as the value
returned by the function.  The \mymxstatustype\ structure is a fairly
simple structure that has only three element.  It is defined as follows:
%
\begin{verbatim}
    typedef struct {
        long code;             /* The error code. */
        const char *location;  /* Function name where the error occurred. */
        char *message;         /* The specific error message. */
    } mx_status_type;
\end{verbatim}
%
Most MX functions will return to their caller either with a line like this
%
\begin{verbatim}
    return MX_SUCCESSFUL_RESULT;
\end{verbatim}
%
if the function was successful, or they will do something like this
%
\begin{verbatim}
    ...
    static const char fname[] = "mx_test_function()";
    ...
    return mx_error( MXE_PERMISSION_DENIED, fname,
        "You do not have sufficient privilege to perform this test." );
    ...
\end{verbatim}
%
In the latter case, by default the MX program will send to \myvar{stderr}
a message that looks like this
%
\begin{verbatim}
    MXE_PERMISSION_DENIED in mx_test_function():
    -> You do not have sufficient privilege to perform this test.
\end{verbatim}
%
It is possible to redirect or suppress such messages using the functions
described below in Section~\ref{subsec:redirecting}.

Note that, by convention, most MX functions will start with a definition
of the form
%
\begin{verbatim}
    static const char fname[] = "mx_function_name()";
\end{verbatim}
%
The C99 standard has now added an equivalent feature to this.  However,
most of our supported platforms do not yet support the C99 version of
the C standard, so we must continue to add our own function name strings
for the forseeable future.

\subsection{mx\_setup\_database\_from\_array()}

\myfunction{mx\_setup\_database\_from\_array()} is an alternate to
\myfunction{mx\_setup\_database()} that reads in the records
from an array of character strings instead of a disk file.
This function may be used as follows:
\begin{verbatim}
    ....
    #define NUM_RECORDS    2
    ....
    MX_RECORD *mx_database;
    char db_array[NUM_RECORDS][80];
    char server_name[] = "192.168.137.3";
    long server_port   = 9727;
    mx_status_type mx_status;

    snprintf( db_array[0], sizeof(db_array[0]),
            "adserver server network tcp_server \"\" \"\" 0x20000000 %s %ld",
                                        server_name, server_port );

    strlcpy( db_array[1],
      "ad device area_detector network_area_detector \"\" \"\" 8 adserver ad",
                    sizeof(db_array[1]) );

    mx_status = mx_setup_database_from_array( &mx_database,
                                                    NUM_RECORDS, db_array );

    if ( mx_status.code != MXE_SUCCESS )
            return mx_status;
    ....
\end{verbatim}

\subsection{mx\_get\_record()}

In order to use a device controlled by MX, you must get a pointer to
the \mymxrecord\ object describing it.  This operation is performed
by the function \myfunction{mx\_get\_record()}.  Here is an example
of using \myfunction{mx\_get\_record()}:
%
\begin{verbatim}
    ...
    MX_RECORD *mx_database;
    MX_RECORD *ad_record;
    char ad_record_name[] = "ad";

    ad_record = mx_get_record( mx_database, ad_record_name );

    if ( ad_record == NULL ) {
        return mx_error( MXE_NOT_FOUND, fname,
        "The record '%s' was not found in the running MX database.",
                ad_record_name );
    }
    ...
\end{verbatim}

\myfunction{mx\_get\_record()} is a fairly simple function.  You hand it
a pointer to the MX database and the name of the record you want to
find and it either returns a pointer to the new record or a NULL pointer
if the record was not found.  Note that the record name you specify
{\bf must} match the name in your client side database file.  Otherwise,
the record will not be found.

\subsection{Redirecting Output}
\label{subsec:redirecting}

MX has four different classes of output that it sends to the user.
These include \textit{debug}, \textit{info}, \textit{warning}, and
\textit{error} messages.  By default, all of these messages are sent
to the \textit{stderr} stream.
MX provides four functions that can potentially redirect each of these
types of output to a different location.  These are:
\myfunction{mx\_set\_debug\_output\_function()},
\myfunction{mx\_set\_info\_output\_function()},
\myfunction{mx\_set\_warning\_output\_function()}, and
\myfunction{mx\_set\_error\_output\_function()}.

Each one of these functions takes a single argument which is a pointer
to a function that takes a \textit{char *} as its single argument and
which returns void.  For example, if we define the following function
%
\begin{verbatim}
    static void my_info_output( char *string )
    {
        printf( "MY_INFO_OUTPUT: %s\n", string );
    }
\end{verbatim}
%
and then make the call
%
\begin{verbatim}
    mx_set_info_output_function( my_info_output_function );
\end{verbatim}
%
then subsequent calls like this
%
\begin{verbatim}
    mx_info("This is a test.");
\end{verbatim}
%
will generate output like this
%
\begin{verbatim}
    MY_INFO_OUTPUT: This is a test.
\end{verbatim}

\subsection{Example for mx\_setup\_database()}

Here we show a complete example that loads an MX database, gets a pointer
to the area detector record, and finishes by checking that it is indeed an
\myfield{network\_area\_detector} record.
%
\input example1a
%
This example introduces a few new features.  First are the MX include file
definitions
%
\begin{verbatim}
    #include "mx_util.h"
    #include "mx_record.h"
    #include "mx_driver.h"
\end{verbatim}
%
The first include file \myfilename{\$MXDIR/include/mx\_util.h} contains 
a large number of utility definitions and functions.  In particular,
it is the header file that defines \mymxstatustype.  The second header file
\myfilename{\$MXDIR/include/mx\_record.h} defines the \mymxrecord\ structure
as well as a variety of other structures and generic functions to manipulate
records.  All of the MX functions in the above example are defined in
\myfilename{mx\_record.h}.  
The last include file named 
\myfilename{\$MXDIR/include/mx\_driver.h} contains a
list of the numerical driver type codes and is included in this program
in order to get the definition of the MXT\_AD\_NETWORK macro.

Two other additions of note are the the use of the \myds{mx\_type} field
of the \mymxrecord\ structure in the statement
\begin{verbatim}
        if ( area_detector_record->mx_type != MXT_AD_NETWORK ) {
\end{verbatim}
and the use of the function \myfunction{mx\_get\_driver\_name()} which
returns the character string name of the driver for this record.  It will
always be the same text which appears in the fourth field of the MX record
definition in the MX database file.

\subsection{Example for mx\_setup\_database\_from\_array()}
\label{subsec:mxsetupdatabasefromarrayexample}

Here is the same example as in the previous section rewritten to
use \myfunction{mx\_setup\_database\_from\_array()}:
%
\input example1b
%

\section{Reading and Writing Area Detector Settings}

MX has a variety of functions for reading and writing internal area
detector settings.  The following list summarizes the functions available
of this type.
%
\begin{description}

  \item[mx\_area\_detector\_get\_maximum\_framesize()]\ \newline
	This function reports the resolution that the detector has
	if it is in unbinned mode.
  \item[mx\_area\_detector\_get\_framesize()]\ \newline
  	This function reports the current resolution of the detector.
  \item[mx\_area\_detector\_set\_framesize()]\ \newline
        This function sets the the resolution of the detector to the
	nearest size that is actually supported by the detector.
  \item[mx\_area\_detector\_get\_image\_format()]\ \newline
  	Returns a constant that describes the image format.
  \item[mx\_area\_detector\_get\_bytes\_per\_pixel()]\ \newline
  	Returns the number of bytes that correspond to a pixel.
	There exist image formats for which this ratio is not an integer,
	so \myfunction{mx\_area\_detector\_get\_bytes\_per\_pixel()}
	reports back the bytes per pixel as a C \textit{double} rather
	than as an integer.
  \item[mx\_area\_detector\_get\_bytes\_per\_frame()]\ \newline
  	Returns the number of bytes in an image frame using the
	current image format and the current framesize.
  \item[mx\_area\_detector\_get\_bits\_per\_pixel()]\ \newline
  	Returns the resolution in bits of a single pixel.
  \item[mx\_area\_detector\_get\_trigger\_mode()]\ \newline
  	Reports whether the area detector is using internal
	or external triggering.
  \item[mx\_area\_detector\_set\_trigger\_mode()]\ \newline
  	Specifies whether the area detector should use internal
	or external triggering.
\end{description}

\section{Internal Detector Registers}

Each kind of detector has a variety of internal registers that
are specific to that model.  Those internal registers are read and written
using the following set of functions.  Each register is referred to by
an ASCII name.  The following functions are provided for reading and writing
internal registers.
%
\begin{description}
  \item[mx\_area\_detector\_get\_register()]
  \item[mx\_area\_detector\_set\_register()]\vspace{-0.3cm}\ \newline
  	These two functions read and write register values as longs.
\end{description}

\section{Sequences}
\label{sec:sequences}

For an area detector, a \textit{sequence} is a series of one or more
image frames that are taken after a single trigger is sent to the area
detector.  In the most general case, each frame can have a different
exposure time and each pair of frames can be separated by a different
separation time.

In MX, the instructions for taking a sequence are encoded in an
\mysequenceparams\ structure.  This structure is found in the MX
header file \myfilename{\$MXDIR/include/mx\_image.h} and is
defined like this:
\begin{verbatim}
    typedef struct {
            long sequence_type;
            long num_parameters;
            double parameter_array[MXU_MAX_SEQUENCE_PARAMETERS];
    } MX_SEQUENCE_PARAMETERS;
\end{verbatim}

The \myvar{sequence\_type} structure member specifies the type of
sequence to be executed.  The \myvar{parameter\_array} member contains
all of the parameters used by the particular type of sequence, while
\myvar{num\_parameters} tells you how many parameters are in the array.
Bear in mind that not all types of sequences supported by MX are available
for all types of area detectors.

The \myfunction{mx\_area\_detector\_set\_sequence\_parameters()}
function can be used to specify the parameters for the next sequence
to be run and \myfunction{mx\_area\_detector\_get\_sequence\_parameters()}
can be used to report the current sequence parameter settings.
Here is an example of how to use
\myfunction{mx\_area\_detector\_set\_sequence\_parameters()}
for One-shot mode, which
is used to take one frame and then stop:
\begin{verbatim}
    ...
    MX_RECORD *ad_record;
    MX_SEQUENCE_PARAMETERS seq_params;
    ...
    seq_params.sequence_type = MXT_SQ_ONE_SHOT;
    seq_params.num_parameters = 1;
    seq_params.parameter_array[0] = 0.5;  /* Exposure time of 0.5 seconds. */

    mx_status = mx_area_detector_set_sequence_parameters( ad_record,
                                                           &seq_params );
    if ( mx_status.code != MXE_SUCCESS )
        return mx_status;
    ....
\end{verbatim}

However, each sequence type has a wrapper function that can be used as
a simplified interface to that type of sequence.  Thus, for the one-shot
case above, it would be more common to use this method instead:
\begin{verbatim}
    ...
    MX_RECORD *ad_record;
    ...
    /* Request a single frame with a 0.5 second exposure time. */

    mx_status = mx_area_detector_set_one_shot_mode( ad_record, 0.5 );

    if ( mx_status.code != MXE_SUCCESS )
        return mx_status;
    ....
\end{verbatim}
%
A variety of convenience functions have been defined
for setting up particular kinds of sequences.
Please note that not all types of sequences are available for all types
of detectors.
%
\begin{description}
  \item[mx\_area\_detector\_set\_one\_shot\_mode()]\ \newline
  	A one-shot sequence takes a single frame for the requested
	exposure time and then stops.
  \item[mx\_area\_detector\_set\_continuous\_mode()]\ \newline
  	A continuous sequence repeatedly takes frames for the requested
	exposure time, without any explicit gaps between the frames
	until commanded to stop.  Each new frame overwrites the previous
	frame.  This mode is useful for live display of images from
	the detector.
  \item[mx\_area\_detector\_set\_multiframe\_mode()]\ \newline
  	This type of sequence takes a specified number of frames with
	each frame going into a separate frame buffer.  All of the frames
	have the same exposure times and the gaps between the frames are
	all the same as well.
  \item[mx\_area\_detector\_set\_circular\_multiframe\_mode()]\ \newline
  	This mode is almost identical to the multiframe mode.  However,
	after the detector takes the last requested frame, it loops
	back to the start of the frame sequence and starts overwriting
	old frames.
  \item[mx\_area\_detector\_set\_strobe\_mode()]\ \newline
  	This type of sequence takes a specified number of frames with
	each frame going into a separate frame buffer.  The start of
	exposure for each frame is triggered by an external trigger.
	This mode can be thought of as edge-triggered.
	Each frame has the same exposure time.
  \item[mx\_area\_detector\_set\_bulb\_mode()]\ \newline
  	This type of sequence takes a specified number of frames with
	each frame going into a separate frame buffer.  For each frame,
	the external trigger signal controls the start and the end of
	the exposure time for each frame.  The exposure starts when
	the external trigger goes high and ends when the external
	trigger goes low.  This mode can be thought of as level-triggered.
  %
  \item[\textit{Aviex PCCD-170170 specific modes}]
  %
  \item[mx\_area\_detector\_set\_geometrical\_mode()]
  \textit{(PCCD-170170)}\newline
	In this mode, the first frame and first gap are taken for the
	specified exposure and gap times.  For each subsequent frame,
	the exposure time and gap times are multiplied by another factor
	of the exposure and gap multipliers.
  \item[mx\_area\_detector\_set\_streak\_camera\_mode()]
  \textit{(PCCD-170170)}\newline
  	In this mode, the detector repeatedly reads in a small number
	of lines from the center of the bottom half of the detector.
	These lines are concatenated into one large image frame, which
	can have a much larger number of rows than a normal image frame.
  \item[mx\_area\_detector\_set\_subimage\_mode()]
  \textit{(PCCD-170170)}\newline
  	In this mode, the detector reads out a sequence of subimages
	that are read from the center of the bottom half of the detector.
	The subimages are concatenated into on image frame, which can be 
	no larger than a single full frame image.
\end{description}

\section{Actions}

The functions in this section command the area detector to start a
data acquisition sequence and then report on the status of this sequence.

\begin{description}
  \item[mx\_area\_detector\_arm()]\ \newline
  	Tells the area detector to perform all the preliminary setup
	required to be ready to start an image sequence.  If external trigger
	is enabled, the first trigger after the arm finishes will start
	the imaging sequence.
  \item[mx\_area\_detector\_trigger()]\ \newline
  	Sends a software trigger to the area detector that tells it to
	start the imaging sequence.
  \item[mx\_area\_detector\_start()]\ \newline
  	This is a utility function that invokes 
	\myfunction{mx\_area\_detector\_arm()} followed by
	\myfunction{mx\_area\_detector\_trigger()}.
  \item[mx\_area\_detector\_stop()]\ \newline
  	This tells the area detector to stop an in-progress imaging sequence
	after the current frame completes.
  \item[mx\_area\_detector\_abort()]\ \newline
  	This tells the area detector to stop an in-progress imaging sequence
	as quickly as possible.  In general, the frame being taken at the
	time of the abort will be lost.
  \item[mx\_area\_detector\_get\_last\_frame\_number()]\ \newline
  	Reports the frame number of the most recently acquired frame.
	Before the first frame (frame 0) is taken, it will return
	the value -1.
  \item[mx\_area\_detector\_get\_total\_num\_frames()]\ \newline
  	Reports the total number of frames acquired since the
	MX server program started.
  \item[mx\_area\_detector\_get\_status()]\ \newline
  	Returns a status flags value that describes the current state of
	the area detector.  The long integer returned is a bitmap in which
	each bit stands for a different status flag.
  \item[mx\_area\_detector\_get\_extended\_status()]\ \newline
  	This function returns the last frame number, the total number of
	frames, and the status flags in one call.
  \item[mx\_area\_detector\_is\_busy()]\ \newline
  	This function reads out the status flag from the detector and
	returns TRUE if any of the following bits are set:
	MXSF\_AD\_ACQUISITION\_IN\_PROGRESS (0x1),
	MXSF\_AD\_CORRECTION\_IN\_PROGRESS (0x2),
	and MXSF\_AD\_CORRECTION\_MEASUREMENT\_IN\_PROGRESS (0x4).
  	
\end{description}

\section{Frame Transfer}

\begin{description}
  \item[mx\_area\_detector\_setup\_frame()]\ \newline
  	This function creates a local \mymximageframe\ structure that can
	be used to hold a frame from the area detector.
  \item[mx\_area\_detector\_readout\_frame()]\ \newline
  	This function tells the area detector to readout the contents
	of the specified frame number into the image buffer
	of the MX server.
  \item[mx\_area\_detector\_transfer\_frame()]\ \newline
  	This function transfers the contents of one of the frame buffers
	described in Section~\ref{subsec:framebuffertypes}\ 
	into the frame buffer that was
	configured by \myfunction{mx\_area\_detector\_setup\_frame()}.
  \item[mx\_area\_detector\_load\_frame()]\ \newline
  	This function loads an image frame from the specified file
	into one of the frame buffers described in
	Section~\ref{subsec:framebuffertypes}.
	The filename specified must refer to a file found on the
	detector computer itself and must use the image format
	configured for this area detector.
  \item[mx\_area\_detector\_save\_frame()]\ \newline
  	This function saves one of the frame buffers described in
	Section~\ref{subsec:framebuffertypes}\ to the specified file.
	The filename specified must refer to a file found on the
	detector computer itself and will use the image format
	configured for this area detector.
  \item[mx\_area\_detector\_copy\_frame()]\ \newline
  	This function copies an image frame from one of the frame buffers
	described in Section~\ref{subsec:framebuffertypes}\ 
	to another of the frame buffers.
\end{description}

\ \newline
\textbf{Utility Functions}

\begin{description}
  \item[mx\_area\_detector\_get\_frame()]\ \newline
  	This is a utility function that reads out, corrects, and then
	transfers the contents of the
	specified image frame number to the specified \mymximageframe\
	structure.  This function invokes the following functions
	\linebreak
	in order: \myfunction{mx\_area\_detector\_setup\_frame()}
	followed by \myfunction{mx\_area\_detector\_readout\_frame()} 
	followed by
	\linebreak
	\myfunction{mx\_area\_detector\_correct\_frame()} 
	and finishing with \myfunction{mx\_area\_detector\_transfer\_frame()} 
  \item[mx\_area\_detector\_get\_sequence()]\ \newline
  	This is a utility function that fills in the frames in
	an \mymximagesequence\ structure by repeated calls to 
	\myfunction{mx\_area\_detector\_get\_frame()}.
\end{description}

\section{Frame Correction}

A hexadecimal \myfield{correction\_flags} field is used for determining
which corrections are made.  The bits in the correction flags use the
bit definitions made in Section~\ref{subsec:framebuffertypes}.

\begin{description}
  \item[mx\_area\_detector\_get\_correction\_flags()]\ \newline
  	Gets the current correction flag settings.
  \item[mx\_area\_detector\_set\_correction\_flags()]\ \newline
  	Sets the correction flags.
  \item[mx\_area\_detector\_correct\_frame()]\ \newline
  	This function causes all of the requested corrections to be
	performed on the frame in the image frame buffer of the
	detector computer.  Normal MX client programs should use
	this function rather than the following function.
  \item[mx\_area\_detector\_frame\_correction()]\ \newline
  	This function supplies pointers to the image frames to be
	used for image corrections.  Since these frames are normally
	located on the detector computer, this function should normally
	only be invoked on the detector computer.
  \item[mx\_area\_detector\_measure\_correction\_frame()]\ \newline
  	This function can be used to create new dark current
	and flood field frames.
  \item[mx\_area\_detector\_measure\_dark\_current\_frame()]\ \newline
  	This is a macro wrapper for 
	\myfunction{mx\_area\_detector\_measure\_correction\_frame()}
	that is only used for dark current measurements.
  \item[mx\_area\_detector\_measure\_flood\_field\_frame()]\ \newline
  	This is a macro wrapper for 
	\myfunction{mx\_area\_detector\_measure\_correction\_frame()}
	that is only used for flood field measurements.
\end{description}

\section{Region of Interest (ROI) Functions}
%
\begin{description}
  \item[mx\_area\_detector\_get\_roi()]\ \newline
	Reports the X and Y dimensions in binned coordinates 
	for the requested software ROI number.
  \item[mx\_area\_detector\_set\_roi()]\ \newline
	Sets the X and Y dimensions in binned coordinates
	for the requested software ROI number.
  \item[mx\_area\_detector\_get\_roi\_frame()]\ \newline
  	This function reads out the contents of the requested software
	ROI from the original \mymximageframe\ structure
	and transfers it to another \mymximageframe\ structure
	that is only large enough to hold the ROI contents.
\end{description}

\section{Image Functions}

MX comes with a number of functions that operate directly on 
\mymximageframe\ structures and which do not involve the area detector at all.
These functions are defined in the header file 
\myfilename{\$MXDIR/include/mx\_image.h}.

\begin{description}
  \item[mx\_image\_alloc()]\ \newline
  	This function creates a new \mymximageframe\ structure.
	You must specify the image type, the frame size, the image format,
	the pixel order, the bytes per pixel, the header length, and
	the image length.  If you want an \mymximageframe\ structure
	that is compatible with your area detector, you are better off
	letting \myfunction{mx\_area\_detector\_setup\_frame()} or
	\myfunction{mx\_area\_detector\_get\_frame()} do it for you,
	instead of invoking this function directly.
  \item[mx\_image\_free()]\ \newline
  	This function frees all of the memory in use by an existing
	\mymximageframe\ structure.
  \item[mx\_image\_copy\_frame()]\ \newline
  	This copies the contents of one \mymximageframe\ to another.
  \item[mx\_image\_get\_exposure\_time()]\ \newline
  	This returns the exposure time in seconds of the exposure that
	was used to take the original image data.
	This information is generally used to perform scaled 
	dark current corrections.
	If the image has been read from an image file whose header
	does not contain the exposure time, the exposure time is set to 1.
  \item[mx\_image\_get\_average\_intensity()]\ \newline
  	This returns the average of the pixel values in the specified
	image frame.
  \item[mx\_image\_get\_image\_data\_pointer()]\ \newline
  	This returns a pointer to a 1-dimensional buffer containing
	the image data inside an \mymximageframe\ structure.
	If the image size or format of a new frame read into an
	existing \mymximageframe\ structure by
	\myfunction{mx\_area\_detector\_get\_frame} or
	\myfunction{mx\_area\_detector\_transfer\_frame}
	is different than that
	of the image data that was already in the structure,
	then MX may replace the existing image data buffer with a new one.
	If you need a pointer to the 1-dimensional image data buffer,
	it is safest to reinvoke 
	\myfunction{mx\_image\_get\_image\_data\_pointer()}
	after each new frame is read into the \mymximageframe\ structure.
  \item[mx\_image\_copy\_1d\_pixel\_array()]\ \newline
  	This function copies the pixel data from an \mymximageframe\
	structure to a 1-dimensional buffer supplied by the caller.
  \item[mx\_image\_read\_file()]\ \newline
  	This function reads the requested image file
	in the requested format into the supplied \mymximageframe\
	structure.  The specified filename must exist on the computer
	that is invoking this function.
  \item[mx\_image\_write\_file()]\ \newline
  	This function writes the contents of the supplied \mymximageframe\
	structure in the requested format into the requested image file.
	The file created will be on the computer that is invoking this function.

%	\textit{(\FIXME\ The above two functions currently only support 
%	PNM format.  We must implement SMV format at least, before
%	releasing the package.)}

  \item[mx\_image\_get\_format\_type\_from\_name()]
  \item[mx\_image\_get\_format\_name\_from\_type()]\ \newline

  	These are two utility functions that convert back and forth
	between ASCII names for the formats such as \textit{GREY16}
	and the corresponding numerical format values.
\end{description}


\section{Example Programs}

Having shown an overview of the API used to control area detectors with MX,
we now show some complete programs that use the API.

\subsection{Acquiring and Saving Images - example2.c}

This program takes a sequence of image frames from an area detector.
The program demonstrates both saving them to a file on the detector
computer and transferring them to the client and then saving them
on the client computer.

\input example2

\subsection{Measuring Detector Dark Currents - example3.c}

\input example3

\subsection{Reading Out a Region Of Interest (ROI) - example4.c}

\input example4

