382 lines
12 KiB
C
382 lines
12 KiB
C
/*
|
|
* 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(PTCHAR 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(PTCHAR 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, PTCHAR 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, PTCHAR 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, PTCHAR 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, PTCHAR 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
|
|
PTCHAR ValueName, // name of value to read
|
|
PTCHAR 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);
|
|
|
|
|
|
|
|
#endif //_VCUSER_H_
|