/**
 * This is a translation to C of the C++ CvBase class (cvbase.cpp, cvbase.hpp).
 *
 * Opens a display window and reads input frames from either a camera or video
 * file.  Processes each frame (no operation by default) and displays the
 * results.
 *
 * Provides basic functions to pause/unpause the live input, emit debugging
 * information for selected frames, and to save both raw capture and processed
 * images.
 *
 * See cvdemo.c for a simple usage example and build instructions.
 *
 * You can use this module as a base for your own work.  Just replace the file
 * cvdemo.c with your own work. The main thing you probably need to change is
 * the process() function.  Also, the various *Ext*() functions are hooks that
 * mostly do nothing cvdemo.c, but are convenient places for you to insert your
 * own code.
 *
 * If you do use this module, it is best if you do not modify it.  I.e., use
 * the files cvbase.h and cvbase.c as you download them, with no modifications.
 * That way if it becomes necessary for us to supply an updated version of the
 * files (e.g. with bugfixes) you will be able to just easily drop in the
 * replacement, rather than having to merge it line-by-line with your code.
 *
 * @author vona
 **/

#include "cv.h"
#include "highgui.h"

/** Default input specification (use next available camera). **/
#define DEF_INPUT "-1"

/** Default width and height for camera input. **/
#define DEF_CAM_W 640
#define DEF_CAM_H 480

/** Default maximum frames per second. **/
#define DEF_MAX_FPS 10.0f

/** Default minimum inter-frame delay in ms. **/
#define DEF_MIN_DELAY_MS 5

/** Default application name. **/
#define DEF_APPNAME "cvbase"

/** The cv capture structure. **/
extern CvCapture *cap;

/** Maximum frames per second. **/
extern float maxFPS;

/** Minimum inter-frame delay. **/
extern int minDelayMS;

/** Application name. **/
extern const char *appname;

/** The file save image, if any (freed by destructor iff allocated). **/
extern IplImage *saveImage;

/** Most recently captured image, if any (do not mutate or free). **/
extern IplImage *capImage;

/** Most recently processed image, if any (do not free). **/
extern IplImage *procImage;

/** Most recent captured frame number. **/
extern int frameN;

/** Milliseconds per OpenCV clock tick. **/
extern double msPerTick;

/** Whether processing is currently paused. **/
extern int paused;

/** Whether debug is requested for next frame. **/
extern int dbg;

/** Current time in milliseconds according to OpenCV clock. **/
double nowMS();

/** Display command line help. **/
void cmdHelp();

/** Whether the camera index is optional on the command line. **/
int camIndexOptional();

/** Display extra command line help, for extensions. **/
void cmdHelpExt();

/** Extra command line parameters, for extending. **/
const char *cmdHelpExtParams();
  
/** Display GUI help. **/
void guiHelp();

/** Display extra GUI help, for subclasses. **/
void guiHelpExt();

/** 
 * Process the given frame.
 *
 * Default impl is identity.
 *
 * Note that the passed image may not be mutated.  So to do any significant
 * processing, you will need to allocate your own return image.  It is
 * typically best to do this once for the first frame, store the results in
 * static variables, and then deallocate any allocated space in
 * cleanupExt().
 *
 * All frames are guaranteed to have the same dimensions and pixel format.
 *
 * This will be called for every iteration of mainLoop(), even while paused.
 * You may use the various static variables #frameN, #capImage, #paused, #dbg,
 * etc. to determine what operations to perform.  Of course, when writing an
 * extension, you may also add your own fields.
 *
 * @return the processed image, null will cause image display to be skipped
 * for this frame
 **/
IplImage *process(IplImage *frame);

/**
 * Handle keypresses.
 *
 * @return 1 to continue processing frames, 0 to end program
 **/
int handleKey(int code);

/**
 * Keypresses not handled by the default implementation of handleKey() are
 * passed here.
 *
 * Default impl just prints the keycode.
 *
 * Overriding this is one way that extensions can handle extra keypresses.
 **/
int handleKeyExt(int code);

/**
 * Save an image to file using the OpenCV API.
 *
 * @return 1 on success.
 **/
int save(const char *filename, IplImage *image);

/** Releases memory and frees resources. **/
void cleanup();

/** Perform any extra cleanup, for extending. **/
void cleanupExt();

/**
 * Initialize members based on command line arguments.
 *
 * In particular, this constructs #cap and opens the main window (named
 * #appname).
 *
 * @return the number of arguments eaten, other than the first, which is
 * always the invoked program name
 **/
int init(int argc, char *argv[]);

/**
 * Extra initialization, for extensions.
 *
 * @param ate the number of command line arguments already eaten by init()
 *
 * @return the total number of arguments eaten, other than the first, which is
 * always the invoked program name
 **/
int initExt(int argc, char *argv[], int ate);

/** 
 * Main frame processing loop.
 *
 * Default impl acquires a new frame, calls process(), displays the result
 * (if any), delays for the remainder of the minimum frame time (inverse of
 * #maxFPS), and handles user input.
 **/
void mainLoop();