# E.S.O. - VLT project 
#
# "@(#) $Id: RtdCamera.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  20 Jul 95  Created

NAME
RtdCamera - A C++ class for managing realtime image updates

SYNOPSIS
#include "RtdCamera.h"

class RtdCamera {
protected:
    char* name_;		// some unique name (name of Tk image...)
    int verbose_;		// flag: if true, print diagnostic messages
    Tcl_Interp* interp_;	// Tcl interp (for file events, error handling)
    rtdIMAGE_EVT_HNDL* eventHndl_; // image event handle
    int evtError_;		// error count for image events
    char* eventScript_;		// tcl script to evaluate for each event
    void* shmPtr_;		// pointer to shared memory area for image
    int shmId_;			// shared memory ID for image event
    char* camera_;		// camera name
    int attached_;		// flag: true if we are attached to the image event
				// server
    int width_, height_;	// image dimensions
    int type_;			// image type

    // member called by fileEventProc for realtime image events
    int fileEvent();

    // called to display new image from shared memory
    // (defined in a derived class)
    virtual int display(int frameId, int type, int width, int height, void* data) = 0;
    
    // start accepting events from the camera
    int attach(const char* camera);

    // stop accepting events from the camera
    int detach();

public:

    // constructor
    RtdCamera(const char* name, Tcl_Interp*, int verbose);
    
    // destructor 
    ~RtdCamera();

    // static file handler, called by Tk file handler for realtime image events
    static void fileEventProc(ClientData, int mask);

    // start/stop/pause or continue accepting images
    int start(const char* camera);
    int stop();
    int pause();
    int cont();

    // make a allocated copy of the shared memory image data
    void* copyImage();

    // return the current status of the camera
    int paused();
    int attached();
    int stopped();
    void* shmPtr();
};

DESCRIPTION
RtdCamera is the abstract base class for managing real-time images
coming from a CCD camera. It is designed as a base class, so that it
doesn't have to know anything about how to actually display an image.
Class RtdImage derives a simple class from this base class and
redefines the "display" method to display the incoming image.

An instance of this class (actually a derived class) is created for
the rtdimage(n) "camera start" command. It opens a connection to the
RtdServer(1) daemon process and sets up a Tk file event handler to
listen for image events. When an image event is received, this class
decodes it and calls the virtual "display" method to display the
image.

METHODS	
int fileEvent()
	This method is called when there is a message to read from the
	realtime event server. Read the message and call a virtual
	method to display the image and evaluate the tcl event script,
	if there is one (not currently used, see rtdimage(n) camera
	command).

void* copyImage() 
	return a malloc'ed copy of the shared memory image data.

void fileEventProc(ClientData clientData, int mask)
	This static method is called when there is a message to read
	from the realtime event server: pass it on to a member
	function.

int attach(const char* camera) 
	Start accepting events from the camera.

int detach() 
	Stop accepting events from the camera.


int start(const char* camera) 
	Start accepting images from the named camera.  The "name"
	argument is some string that identifies the caller, such as
	the image name.  "camera" is a string that identifies the
	camera.

int stop()
	Stop accepting images from the camera.

int pause()
	This is like stop, but keeps the camera around so that you can
	use "cont" to continue.

int cont()
	Continue the camera after a pause.

SEE ALSO
RtdImage, rtdImageEvt, RtdServer(1), rtdimage(n)
-----------------------------------------------------------------------
