windows-nt-4.0/private/windows/media/vidcap/inc/vcuser.h

/*
 * Copyright Microsoft Corporation, 1993 - 1995. All Rights Reserved.
 */

/*
 * vcuser.h
 *
 * 32-bit Video Capture driver
 * User-mode support library
 *
 * define functions providing access to video capture hardware. On NT,
 * these functions will interface to the kernel-mode driver.
 *
 * include vcstruct.h before this.
 *
 * Geraint Davies, Feb 93
 */

#ifndef _VCUSER_H_
#define _VCUSER_H_

/*
 * capture device handle. This structure is opaque to the caller
 */
typedef struct _VCUSER_HANDLE * VCUSER_HANDLE;

/*
 * these are the parameters we need to issue a DriverCallback. A
 * pointer to one of these structs is passed on StreamInit
 * If the pointer is null, we don't need callbacks.
 */
typedef struct _VCCALLBACK {
    DWORD dwCallback;
    DWORD dwFlags;
    HDRVR hDevice;
    DWORD dwUser;
} VCCALLBACK, * PVCCALLBACK;


/*
 * open the device and return a capture device handle that can be used
 * in future calls.
 * The device index is 0 for the first capture device up to N for the
 * Nth installed capture device.
 *
 * If pDriverName is non-null, then we will open the Nth device handled
 * by this driver. (Current implementation supports only one device per
 * drivername.)
 *
 * This function returns NULL if it is not able to open the device.
 */
VCUSER_HANDLE VC_OpenDevice(PWCHAR pDriverName, int DeviceIndex);


/*
 * close a capture device. This will abort any operation in progress and
 * render the device handle invalid.
 */
VOID VC_CloseDevice(VCUSER_HANDLE vh);


/*
 * Configuration.
 *
 * These functions perform device-dependent setup affecting the
 * target format, the source acquisition or the display (overlay).
 *
 * The structures passed are not interpreted by the vcuser and vckernel
 * libraries except that the first ulong of the struct must contain the
 * size in bytes of the entire structure (see vcstruct.h). It is assumed
 * that the structures are defined and agreed between the user-mode
 * hardware-specific code and the kernel-mode hardware specific code
 */
BOOL VC_ConfigFormat(VCUSER_HANDLE, PCONFIG_INFO);
BOOL VC_ConfigSource(VCUSER_HANDLE, PCONFIG_INFO);
BOOL VC_ConfigDisplay(VCUSER_HANDLE, PCONFIG_INFO);


/*
 * overlay and keying
 *
 * Several different methods are used by devices to locate the overlay
 * area on the screen: colour (either rgb or palette index) and/or
 * either a single rectangle, or a series of rectangles defining a complex
 * region. Call GetOverlayMode first to find out which type of overlay
 * keying is available. If this returns 0, this hardware is not capable
 * of overlay.
 */

/*
 * find out the overlay keying method
 */
ULONG VC_GetOverlayMode(VCUSER_HANDLE);

/*
 * set the key colour to a specified RGB colour. This function will only
 * succeed if GetOverlayMode returned  VCO_KEYCOLOUR and VCO_KEYCOLOUR_RGB
 * and not VCO_KEYCOLOUR_FIXED
 */
BOOL VC_SetKeyColourRGB(VCUSER_HANDLE, PRGBQUAD);

/*
 * set the key colour to a specified palette index. This function will only
 * succeed if GetOverlayMode returned VCO_KEYCOLOUR and not either
 * VCO_KEYCOLOUR_RGB or VCO_KEYCOLOUR_FIXED
 */
BOOL VC_SetKeyColourPalIdx(VCUSER_HANDLE, WORD);

/*
 * get the current key colour. This 32-bit value should be interpreted
 * as either a palette index or an RGB value according to the
 * VCO_KEYCOLOUR_RGB flag returned from VC_GetOverlayMode.
 */
DWORD VC_GetKeyColour(VCUSER_HANDLE vh);

/*
 * set the overlay rectangle(s). This rectangle marks the area in device
 * co-ordinates where the overlay video will appear. The video will be
 * panned so that pixel (0,0) will appear at the top-left of this rectangle,
 * and the video will be cropped at the bottom and right.  The video
 * stream will not normally be scaled to fit this window: scaling is normally
 * determined by the destination format set by VC_ConfigFormat.
 *
 * If VCO_KEYCOLOUR was returned, the video
 * will only be shown at those pixels within the rectangle for which the
 * vga display has the key colour (VC_GetKeyColour() for this).
 *
 * Some devices may support complex regions (VCO_COMPLEX_RECT). In that case,
 * the first rectangle in the area must be the bounding rectangle for
 * the overlay area, followed by one rectangle for each region within it in
 * which the overlay should appear.
 */
BOOL VC_SetOverlayRect(VCUSER_HANDLE, POVERLAY_RECTS);


/*
 * set the offset of the overlay. This changes the panning - ie which
 * source co-ordinate appears as the top left pixel in the overlay rectangle.
 * Initially after a call to VC_SetOverlayRect, the source image will be panned
 * so that the top-left of the source image is aligned with the top-left of the
 * overlay rectangle. This call aligns the top-left of the source image
 * with the top-left of this offset rectangle.
 */
BOOL VC_SetOverlayOffset(VCUSER_HANDLE, PRECT);

/* enable or disable overlay. if the BOOL bOverlay is TRUE, and the overlay
 * key colour and rectangle have been set, overlay will be enabled.
 */
BOOL VC_Overlay(VCUSER_HANDLE, BOOL);

/*
 * enable or disable acquisition.
 * If acquisition is disabled, the overlay image will be frozen.
 *
 * this function will have no effect during capture since the acquisition
 * flag is toggled at each frame capture.
 */
BOOL VC_Capture(VCUSER_HANDLE, BOOL);



/*
 * capture a single frame, synchronously. the video header must point
 * to a data buffer large enough to hold one frame of the format set by
 * VC_ConfigFormat.
 */
BOOL VC_Frame(VCUSER_HANDLE, LPVIDEOHDR);


/*
 * data streaming.
 *
 * Call VC_StreamInit to prepare for streaming.
 * Call VC_StreamStart to initiate capture.
 * Call VC_AddBuffer to add a capture buffer to the list. As each
 * frame capture completes, the callback function specified in
 * VC_StreamInit will be called with the buffer that has completed.
 *
 * If there is no buffer ready when it is time to capture a frame,
 * a callback will occur. In addition, VC_StreamGetError will return
 * a count of the frames missed this session. VC_StreamGetPos will return
 * the position (in millisecs) reached so far.
 *
 * Call VC_StreamStop to terminate streaming. Any buffer currently in
 * progress may still complete. Uncompleted buffers will remain in the
 * queue. Call VC_Reset to release all buffers from the queue.
 *
 * Finally call VC_StreamFini to tidy up.
 */

/*
 * prepare to start capturing frames
 */
BOOL VC_StreamInit(VCUSER_HANDLE,
		PVCCALLBACK,	// pointer to callback function
		ULONG		// desired capture rate: microseconds per frame
);

/*
 * clean up after capturing. You must have stopped capturing first.
 */
BOOL VC_StreamFini(VCUSER_HANDLE);

/*
 * initiate capturing of frames. Must have called VC_StreamInit first.
 */
BOOL VC_StreamStart(VCUSER_HANDLE);

/*
 * stop capturing frames. Current frame may still complete. All other buffers
 * will remain in the queue until capture is re-started, or they are released
 * by VC_StreamReset.
 */
BOOL VC_StreamStop(VCUSER_HANDLE);

/*
 * cancel all buffers that have been 'add-buffered' but have not
 * completed. This will also force VC_StreamStop if it hasn't already been
 * called.
 */
BOOL VC_StreamReset(VCUSER_HANDLE);

/*
 * get the count of frames that have been skipped since the last call
 * to VC_StreamInit.
 */
ULONG VC_GetStreamError(VCUSER_HANDLE);

/*
 * get the current position within the capture stream (ie time
 * in millisecs since capture began)
 */
BOOL VC_GetStreamPos(VCUSER_HANDLE, LPMMTIME);

/*
 * add a buffer to the queue. The buffer should be large enough
 * to hold one frame of the format specified by VC_ConfigFormat.
 */
BOOL VC_StreamAddBuffer(VCUSER_HANDLE, LPVIDEOHDR);


/*
 * playback
 *
 * Call VC_DrawFrame to draw a frame into the frame buffer. You should
 * call VC_Overlay functions to arrange for the frame buffer to appear
 * on screen.
 */
BOOL VC_DrawFrame(VCUSER_HANDLE, PDRAWBUFFER);



/*
 * installation/configuration
 *
 * on NT, the following functions will start and stop the
 * kernel driver. The callback function can write profile information
 * to the registry between stopping the driver (if already running) and
 * re-starting the driver. The kernel driver DriverEntry routine is responsible
 * for reading these values from the registry before calling VC_Init().
 *
 * The win-16 implementation will (?) call the callback to write
 * values to the profile, and then call the HW_Startup function. This function
 * is responsible for calling VC_Init, initialising the callback table and
 * initialising the hardware.
 */

/*
 * opaque pointer to the information we need to access the registry/profile.
 */
typedef struct _VC_PROFILE_INFO * PVC_PROFILE_INFO;


/*
 * open a handle to whatever functions are needed to access the registry,
 * service controller or profile. Must call this function before
 * calls to the other VC_ configuration routines.
 *
 * The argument is the name of the driver. This should be the name of
 * the kernel driver file (without path or extension). It will also be used
 * as the registry key name or profile section name.
 */
PVC_PROFILE_INFO VC_OpenProfileAccess(PWCHAR DriverName);

/*
 * close a profile access handle
 */
VOID VC_CloseProfileAccess(PVC_PROFILE_INFO);


/*
 * takes a PVC_PROFILE_INFO returned from VC_OpenProfileAccess, and
 * returns TRUE if we currently have sufficient privilege to perform
 * driver configuration operations.
 */
BOOL VC_ConfigAccess(PVC_PROFILE_INFO);


/*
 * This function is called once the driver has definitely been unloaded, and
 * the profile entry created, but before the driver is re-loaded. It can write
 * any configuration information to the registry. It should return TRUE if
 * it is ok to load and start the kernel-mode driver, or false if some
 * error has occured.
 */
typedef BOOL (*PPROFILE_CALLBACK)(PVOID);


/*
 * start the hardware-access portion of the driver. Call the callback
 * function at a moment when it is possible to write configuration information
 * to the profile using VC_WriteProfile.
 * Returns DRVCNF_OK if all is ok, DRVCNF_CANCEL for failure, or DRVCNF_RESTART if
 * all is ok but a system-restart is needed before the driver will load correctly.
 */
LRESULT VC_InstallDriver(
	    PVC_PROFILE_INFO pProfile,		// access info returned by OpenProfileAccess
	    PPROFILE_CALLBACK pCallback,	// callback function
	    PVOID pContext			// context info for callback	
);

/*
 * Write a single string keyword and DWORD value to the registry or profile
 * for this driver.
 * This can be re-read from the h/w driver using VC_ReadProfile (in either
 * the kernel-mode vckernel.lib version or user mode in the vcuser version).
 *
 * return TRUE for success or FALSE for failure.
 */
BOOL VC_WriteProfile(PVC_PROFILE_INFO pProfile, PWCHAR ValueName, DWORD Value);

/*
 * Write a single string keyword and DWORD value to the registry or profile
 * for this driver.
 * This writes to HKEY_CURRENT_USER and is typically used to store user defaults.
 *
 * return TRUE for success or FALSE for failure.
 */
BOOL VC_WriteProfileUser(PVC_PROFILE_INFO pProfile, PWCHAR ValueName, DWORD Value);


/*
 * read back a driver-specific DWORD profile parameter that was written with
 * VC_WriteProfile. If the valuename cannot be found, the default is returned.
 */
DWORD VC_ReadProfile(PVC_PROFILE_INFO pProfile, PWCHAR ValueName, DWORD dwDefault);

/*
 * read back a driver-specific DWORD profile parameter that was written with
 * VC_WriteProfileUser.  If the valuename cannot be found, the default is returned.
 * This reads from HKEY_CURRENT_USER and is typically used to store user defaults.
 */
DWORD VC_ReadProfileUser(PVC_PROFILE_INFO pProfile, PWCHAR ValueName, DWORD dwDefault);

/*
 * read a string parameter from the device's profile. returns FALSE
 * if it fails to read the string.
 */
BOOL VC_ReadProfileString(
    PVC_PROFILE_INFO pProfile,		// access info from OpenProfile
    PWCHAR ValueName,			// name of value to read
    PWCHAR ValueString,			// put value here
    DWORD ValueLength			// size of ValueString in bytes
);


/*
 * unload a driver. On NT, this stops and removes the kernel-mode driver.
 * On win-16, this calls the Cleanup callback.
 *
 * return DRVCNF_OK if the unload was successful, DRVCNF_CANCEL if it failed, and
 * DRVCNF_RESTART if a system-restart is needed before the removal takes effect.
 *
 * note that after this operation, the PVC_PROFILE_INFO information is still held
 * open. A call to VC_CloseProfileAccess is still needed before exiting.
 */
LRESULT VC_RemoveDriver(PVC_PROFILE_INFO pProfile);



/*
 * debug macros
 *
 */

#if DBG
    void dbgPrintf(char * szFormat, ...);
    extern int vcuDebugLevel;
    int dbgSetDebugLevel(int dbgLevel);


#define dprintf(_x_)	dbgPrintf _x_
#define dprintf1(_x_)	if (vcuDebugLevel >= 1) dbgPrintf _x_
#define dprintf2(_x_)	if (vcuDebugLevel >= 2) dbgPrintf _x_
#define dprintf3(_x_)	if (vcuDebugLevel >= 3) dbgPrintf _x_
#define dprintf4(_x_)	if (vcuDebugLevel >= 4) dbgPrintf _x_

#else

#define dprintf(_x_)
#define dprintf1(_x_)
#define dprintf2(_x_)
#define dprintf3(_x_)
#define dprintf4(_x_)

#endif

#if DBG
	BOOL FAR PASCAL _Assert(BOOL fExpr, LPSTR szFile, int iLine);

	#define ASSERT(expr)		 _Assert((expr), __FILE__, __LINE__)


#else
	#define ASSERT(expr)		

#endif





#endif //_VCUSER_H_