As installable driver DLLs, video capture drivers provide a DriverProc entry point used to process system messages and device driver specific messages. For general information about installable drivers, the DriverProc entry point, and system messages sent to this entry point, see the Microsoft Windows Programmer's Reference. This chapter includes supplemental information for the system messages. This information describes specifically how video capture drivers should respond to the system messages that are critical to their proper operation.
If the same hardware is required or used for a combination of video capture and video compression, you might combine both of these functions into a common DLL and use a single DriverProc entry point to service them. The common entry point will simplify the coordination of the different functions.
Note:
Because video capture drivers can rely on video compression and decompression drivers for efficient operation, a single driver can handle both video capture, and video compression and decompression services. Video capture drivers use the VIDEO_OPEN_PARMS data structure when they are opened. This structure has the same member definitions as the ICOPEN structure used by video compression and decompression drivers. By examining the fccType member, a combined driver can determine whether it is being opened as a video capture driver or a video compression and decompression driver. (Video capture devices contain the four-character code 'vcap' in this member.) For more information on video compression and decompression drivers, see Video Compression and Decompression Drivers.
The entry-point function, DriverProc, processes messages sent by the system to the driver as the result of an application call to a low-level video capture function. For example, when an application opens a video capture device, the system sends the specified video capture device driver a DRV_OPEN message. The driver's DriverProc function receives and processes this message. Each of the different capture channels will receive a separate DRV_OPEN message.
Note:
Your driver should respond to all system messages. If supplemental information is not provided for them in this chapter, use the definitions provided in the Microsoft Windows Programmer's Reference.
Like other installable drivers, client-applications must open a video capture device before using it and close it when finished using it, so the device will be available to other applications. When a driver receives an open request, it returns a value that the system will use for dwDriverID sent with subsequent messages. When your device driver receives other messages, it can use this value to identify instance data needed for operation. Drivers can use the instance data for information related to the client that opened a device.
It's up to you to decide if your device driver will support more than one client simultaneously. If you do this, though, remember to check the dwDriverID parameter to determine which channel is being accessed.
For DRV_OPEN, the lParam2 parameter contains a pointer to a VIDEO_OPEN_PARMS data structure containing information about the open. This structure has the following members:
typedef struct {
DWORD dwSize; // Specifies the structure size
FOURCC fccType; // Contains 'vcap'
FOURCC fccComp; // Reserved; do not use
DWORD dwVersion; // Command set version
DWORD dwFlags; // Type of channel being opened
DWORD dwError; // Error to return if open fails
LPVOID pV1Reserved; // Reserved; do not use
LPVOID pV2Reserved; // Reserved; do not use
DWORD dwDevNode; // Registry device not for PNP devices
} VIDEO_OPEN_PARMS;
The fccType member of this structure will contain the four character code 'vcap'. Because of the four video capture channels, video capture drivers must examine the flags set in the dwFlags member of the VIDEO_OPEN_PARMS data structure to determine the type of channel being opened. Your driver should be prepared to open (and conversely, close) the video channels in any order.
The following flags are defined for the video channels:
Channel | Description |
VIDEO_EXTERNALIN | An external input channel responsible for loading images into the frame buffer. |
VIDEO_EXTERNALOUT | An external output channel responsible for displaying images in the frame buffer to an external or system monitor, or to an overlay device. |
VIDEO_IN | A video input channel responsible for transferring images from the frame buffer to system memory. This might include a translation step or reformatting of the image. For example, reformatting a 16-bit RGB image to an 8 bit palette image. |
VIDEO_OUT | A video output channel responsible for transferring images into the frame buffer from the CPU. (The sample driver does not use this channel type.) |
The dwVersion member specifies the version of the video capture command set used by MSVIDEO.DLL. The version number lets your driver identify the command set to determine its capabilities. For the initial release of the video capture command set, your driver does not have to detect and adjust itself for multiple versions of the command set. Future versions of your driver can use this value to enable new features that depend on new capabilities of the video capture command set.
The dwError member specifies an error value the driver might return to the client-application if it fails the open.
The dwDevNode member specifies the Device Node for plug and play compatible drivers. For non-Plug and Play devices, this member will be NULL.
Although the Orchid sample capture driver uses the associated VxD merely to interract with the plug and play subsystem, you can optionally move portions of your capture functionality out of the Ring3 DLL and into the VxD. The actual vertical sync interrupt service routine is an obvious candiate for migration.
The VxD portion of the driver is loaded on system boot and receives configuration messages through the AVVXP500_Config_Handler entry point. When the Ring3 DLL is loaded on demand by a capture application, it first obtains the entry point to the VxD by calling the GetVxDEntry function. Next it requests the current resources via the GetVxDInfo function. When this function returns, the Ring3 DLL has a list of IRQ, and port resources previously acquired by the VxD.
Device information (INF) files provide the information that the Windows 95 operating system needs to install the software and information to support a given hardware device. Independent hardware vendors who develop Windows 95 device drivers must also create INF files to explicitly define the resources and files required to support each class of device.
Device information (INF) files provide the information that Windows 95 needs to install a given device and its associated software. IHVs who wish to install their devices and software using the Windows 95 built in installation support must create an INF to describe the device and its installation requirements.
Every INF is a collection of sections which describe a device, the resources required by that device and the installation procedure. Windows 95 New Device Wizard builds its list of installable devices by searching through the INFs. The Device Manager also displays information which originates in the INF. Every hardware INF follows the general organization described below.
Section name | Description |
Version | Contains a simple header that identifies the INF and the class of device this INF supports. |
Class | Defines a new class for this device. This section is optional only as long as the class is already defined |
Manufacturer and Manufacturer Name | Lists all the individual manufacturers of the devices identified in this file and lists all the devices built by that manufacturer. These entries are displayed directly to the user and used to generate the appropriate registry entries. There must always be at least one manufacturer. |
Install | Describes the device driver and physical attributes of the hardware device. It also identifies the names of all the Installation sections that contain information and instructions for installing this device. |
Strings | Defines all localizable strings used in the INF file. |
Miscellaneous Control Sections | Specifies how a device is handled by the Windows 95 user interface. |
If you have a Win3.1 compatible driver which you are not planning to upgrade for plug and play, it is still a good idea to update the INF file so the system can inform the user of possible resource conflicts during installation.
Note
For details on how to create a Windows 95 INF file, refer to the Plug and Play documentation.Video Capture Driver Messages
Installable drivers that do not have plug and play capability can supply a configuration dialog box for users to access through the Drivers option in the Control Panel. The Drivers option sends the DRV_CONFIGURE message to your driver to display the dialog box.
The dialog box should display the name and version number of your device driver. If your device driver supports different interrupt-level and port assignments, it should also support user configuration through the Drivers option in the Control Panel.
Installable drivers that do not have plug and play capability can store interrupt-level and port assignments, and any other hardware-related settings, in a section with the same name as the driver in the user's SYSTEM.INI file. For example, the following SYSTEM.INI section created by the Bravado example driver specifies interrupt level 9 and memory base E:
[Bravado.drv] Interrupt=9 MemoryBase=E
Alternatively, your driver might use its own INI file for this information.
Hardware related settings for plug and play devices is stored in the registry.
Configuring the Channels of a Video Capture Driver
In addition to the configuration dialog box displayed for the DRV_CONFIGURE message, video capture drivers can display a dialog box for each channel. These dialog boxes are the primary means of setting parameters in your device driver. The DVM_DIALOG message requests that the device driver display a dialog box.
When your device driver first gets this message, use the handle in lParam1 to determine which channel is being configured. The sample driver determines the channel from the flags used to open it. It saves these flags as part of its instance data created when it was opened.
The dialog box displayed for each channel sets the characteristics for each channel. If a channel does not support configuration, return DV_ERR_NOTSUPPORTED. The following table suggests the contents of each dialog box:
Channel | Dialog box description |
VIDEO_EXTERNALIN | Displays a dialog box controlling how video (either analog or digital) is captured. The dialog box might set attributes such as contrast, brightness, NTSC,. PAL, .and input source |
VIDEO_EXTERNALOUT | Displays a dialog box controlling how video is displayed on a second monitor or video adapter such as a video overlay card. |
VIDEO_IN | Displays a dialog box controlling how video is transferred from the frame buffer. This includes options such as the format of the video, bit rate, and compression format. |
VIDEO_OUT | Displays a dialog box controlling how video is transferred to the frame buffer. |
When processing the DVM_DIALOG message, check lParam2 for the VIDEO_DLG_QUERY flag prior to displaying the dialog box. If an application uses this flag, it is only determining if a video channel supports a dialog box. For this flag, return DV_ERR_OK if the video channel supports a dialog box. If not, return DV_ERR_NOTSUPPORTED in response to the message.
Video capture drivers might save the settings from these dialog boxes in the section reserved for your device driver in the SYSTEM.INI file. Your driver should append this information to the entries created for the DVR_CONFIGURE messages to this section. For example, the Bravado driver might have this section in the SYSTEM.INI file:
[Bravado.drv] Interrupt=9 MemoryBase=E Hue=10 Saturation=6 InputChannel=2 Contrast=24
Alternatively, a device driver might implement its own method of storing configuration information for each channel.
The video capture format globally defines the attributes of the images transferred from the frame buffer with the video in channel. Attributes include image dimensions, color depth, and the compression format of images transferred. Applications use the DVM_FORMAT message to set or retrieve the format of the digitized image.
The calling application must modify this message with flags to indicate its purpose. Your driver must examine the flags sent with the message to determine the proper response. The flags are specified in lParam1.
The VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET flag indicates if the DVM_FORMAT message is being used to obtain the format or set the format. The DVM_FORMAT message and these flags are sent to your driver when it is opened, and when it is configured with DVM_DIALOG.
When an application opens your driver, it retrieves the initial driver format. (Video capture drivers initially default to a format that efficiently uses the capabilities of the video capture hardware or, if they have been previously configured, they restore the last user specified configuration saved in a disk file.) If this format is acceptable, the application continues its operations. If the format is not acceptable, the application will either immediately close your driver or suggest a very limited format. If the limited format is not acceptable to your driver, the application closes it. (Typically, applications do not accept a format because they cannot allocate enough memory to capture video. A limited format might free enough memory for operation.)
Applications also get the format when the user changes the format. (Users change the format with the VIDEO_IN channel dialog box displayed with the DVM_DIALOG message.) In this case, applications get and retain a copy of the current format prior to sending the DVM_DIALOG message. After the user exits from the DVM_DIALOG dialog box, applications get the new format from your driver. If the application accepts the new format, it uses the VIDEO_CONFIGURE_SET flag to return the format back to your driver. (Your driver should verify that the application has not changed the format information.) If the application does not accept the new format, it restores the format it obtained prior to displaying the dialog box.
The DVM_FORMAT messages uses lParam2 to pass the format information. This parameter contains a pointer to a VIDEOCONFIGPARMS structure. This structure has the following members:
typedef struct tag_video_configure_parms {
LPDWORD lpdwReturn;
LPVOID lpData1;
DWORD dwSize1;
LPVOID lpData2;
DWORD dwSize2;
} VIDEOCONFIGPARMS;
The lpData1 member points to a BITMAPINFOHEADER data structure. The size of this structure is specified in dwSize1.
Changing the format can affect overall dimensions of the active frame buffer as well as bit depth and color space representation. Since changing between NTSC and PAL video standards can also affect image dimensions, applications should request the current format following display of the EXTERNAL_IN channel dialog box.
If an application just wants to know if your driver supports DVM_FORMAT, it sends the VIDEO_CONFIGURE_QUERY flag with the message. (Using the VIDEO_CONFIGURE_QUERY flag without VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET is invalid.) Your device driver should return DV_ERR_OK if it supports the message. Otherwise, it should return DV_ERR_NOTSUPPORTED.
If an application wants to determine the amount of memory it needs to allocate for the format information, it sends the DVM_FORMAT message with the VIDEO_CONFIGURE_GET and VIDEO_CONFIGURE_QUERYSIZE flags set. Your driver should specify the format size in the lpdwReturn member of the VIDEOCONFIGUREPARMS structure.
Video capture drivers might support a source rectangle to specify a portion of an image that is digitized or transferred to the display. External in ports use the source rectangle to specify the portion of the analog image digitized. External out ports use the source rectangle to specify the portion of frame buffer shown on the external output.
Similarly, video capture drivers might support a destination rectangle to specify the portion of the frame buffer or screen used to receive the image. External in ports can use a destination rectangle to specify the portion of the frame buffer used for the digitized video input. External out ports can use the rectangle to specify the client rectangle on the display.
The DVM_DST_RECT and DVM_SRC_RECT messages are used to set and obtain the video source and destination rectangles.The calling application must modify these messages with flags to indicate their exact meaning. Your driver must examine the flags sent with the messages to determine the proper response. The flags are specified in lParam2. The VIDEO_CONFIGURE_SET, VIDEO_CONFIGURE_GET, and VIDEO_CONFIGURE_QUERY flags define the meaning of the DVM_DST_RECT and DVM_SRC_RECT messages:
The VIDEO_CONFIGURE_SET flag indicates the application is setting a source or destination rectangle. The rectangle coordinates are specified in a RECT structure pointed to by lParam1.
If an application sets a source or destination rectangle for an external out channel, your driver will normally receive a series of messages. For these channels, applications normally send both DVM_SRC_RECT and DVM_DST_RECT to your driver to properly set the rectangles. The application follows these messages with DVM_UPDATE. Video overlay devices should paint their key color in response to DVM_UPDATE.
Applications use the VIDEO_CONFIGURE_GET flag to determine the coordinates of the source and destination rectangles. Applications use additional flags with VIDEO_CONFIGURE_GET to indicate if they want the coordinates of the rectangle currently defined, the maximum size of the rectangle, or the minimum size of the rectangle.
Your driver should return the coordinates for the appropriate rectangle in the RECT structure pointed to by lParam1.
An application use the VIDEO_CONFIGURE_QUERY flag to determine if your driver supports VIDEO_CONFIGURE_QUERY or VIDEO_CONFIGURE_SET. (The VIDEO_CONFIGURE_QUERY flag without VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET is invalid.) Your device driver should return DV_ERR_OK if it supports the flag. Otherwise, it should return DV_ERR_NOTSUPPORTED.
Channel capabilities include overlaying video, scaling of images with the source and destination rectangles, and clipping of images with the source and destination rectangles. The DVM_GET_CHANNEL_CAPS message retrieves the channel capabilities of a driver.
Applications use DVM_GET_CHANNEL_CAPS to obtain information about the capabilities of a channel. The lParam1 parameter specifies a far pointer to a
CHANNEL_CAPS data structure and the lParam2 parameter specifies its size. The CHANNEL_CAPS structure has the following members:
typedef struct channel_caps_tag {
DWORD dwFlags;
DWORD dwSrcRectXMod;
DWORD dwSrcRectYMod;
DWORD dwSrcRectWidthMod;
DWORD dwSrcRectHeightMod;
DWORD dwDstRectXMod;
DWORD dwDstRectYMod;
DWORD dwDstRectWidthMod;
DWORD dwDstRectHeightMod;
} CHANNEL_CAPS;
Your driver should use the dwFlags member to return flags indicating its capabilities for overlaying video, and clipping and scaling images with the source and destination rectangles.
If your driver supports changing the size and position of the source rectangle, it should indicate the finest granularity used for changes to the rectangle in the dwSrcRectXMod, dwSrcRectYMod, dwSrcRectWidthMod, and dwSrcRectHeightMod members.
If your driver supports changing the size and position of the destination rectangle, it should indicate the finest granularity used for changes to the rectangle in the dwDstRectXMod, dwDstRectYMod, dwDstRectWidthMod, and dwDstRectHeightMod members. If a channel supports arbitrarily positioned rectangles, with arbitrary sizes, the values above should all be set to 1.
Your driver returns DV_ERR_OK if the message was processed successfully. It returns DV_ERR_NOTSUPPORTED if the message is not supported.
Applications can set and retrieve the palette used with captured video. This gives applications the ability to control and modify the palette used for video sequences. The palette messages apply only to the video in and video out channels. The DVM_PALETTE assigns or obtains palette information and the DVM_PALETTERGB555 message associates an RGB555 palette with a video device channel.
The calling application must modify these messages with flags to indicate their purpose. Your driver must examine the flags sent with the messages to determine the proper response. The flags are specified in lParam1.
The VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET flag modifies the DVM_PALETTE message to indicate that the driver should return the current palette or that the driver should set a new palette. The lParam2 parameter used with DVM_PALETTE contains a pointer to a VIDEOCONFIGPARMS data structure. This structure has the following members:
typedef struct tag_video_configure_parms {
LPDWORD lpdwReturn;
LPVOID lpData1;
DWORD dwSize1;
LPVOID lpData2;
DWORD dwSize2;
} VIDEOCONFIGPARMS;
If the VIDEO_CONFIGURE_SET flag is used with DVM_PALETTE, the lpData1 member points to a LOGPALETTE structure containing the new palette. The size of the memory allocated for the LOGPALETTE structure is specified in the dwSize1 member.
If the VIDEO_CONFIGURE_GET flag is used with DVM_PALETTE, the lpData1 member points to a LOGPALETTE structure used to retrieve the palette. The size of the memory allocated for the LOGPALETTE structure is specified in the dwSize1 member. Your driver should transfer the palette to the structure indicated by lpData1.
If an application just wants to determine the size of the palette, it sends the DVM_PALETTE message with both the VIDEO_CONFIGURE_GET and VIDEO_CONFIGURE_QUERYSIZE flags. Your driver should return the palette size in the lpdwReturn member.
If an application just wants to know if your driver supports DVM_PALETTE and its flags, it also sets the VIDEO_CONFIGURE_QUERY flag with VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET. (The VIDEO_CONFIGURE_QUERY flag without VIDEO_CONFIGURE_GET or VIDEO_CONFIGURE_SET is invalid.) Your device driver should return DV_ERR_OK if it supports the DVM_PALETTE message and the operation indicated with the set or get flag. Otherwise, it should return DV_ERR_NOTSUPPORTED.
DVM_PALETTE does not use the lpData2 and dwSize2 members.
Applications use the DVM_PALETTERGB555 message to associate an RGB555 palette with a video device channel. Only the VIDEO_CONFIGURE_SET and VIDEO_CONFIGURE_QUERY flags apply to this message. The VIDEO_CONFIGURE_SET flag modifies the DVM_PALETTERGB555 message to indicate that the driver should set a new palette. The lParam2 parameter used with DVM_PALETTERGB555 contains a pointer to a VIDEOCONFIGPARMS data structure.
When setting the palette, the lpData1 member points to a LOGPALETTE structure containing the new palette. The lpData2 member points to a 32 kilobyte RGB555 translation table. The device driver uses this table to translate the RGB555 triples into palette colors when capturing data in an 8 bit palette mode. The dwSize1 and dwSize2 members specify the size of the structures indicated by lpData1 and lpData2.
If an application just wants to know if your driver supports DVM_PALETTERGB555, it sends the VIDEO_CONFIGURE_QUERY flag with VIDEO_CONFIGURE_SET. (The VIDEO_CONFIGURE_QUERY flag without VIDEO_CONFIGURE_SET is invalid.) Your device driver should return DV_ERR_OK if it supports the DVM_PALETTERGB555 message. Otherwise, it should return DV_ERR_NOTSUPPORTED.
The DVM_GETVIDEOAPIVER message lets an application interrogate your device driver to determine the version of the video capture command set. Your driver should return VIDEOAPIVERSION in the DWORD buffer that lParam1 points to. This message does not have any flags associated with it.
The DVM_FRAME message lets an application obtain a single frame from the frame buffer.This message is the basis for the simplest form of video capture. Applications might use this to record animated sequences created frame-by-frame or to capture a single still image such as a photograph. The following sequence of operations occurs when a client-application requests the transfer of a single video frame:
1 The client allocates the memory for the data buffer.
2 The client sets a pointer to the empty data buffer in the VIDEOHDR data structure.
3 The client sends the device driver a pointer to the VIDEOHDR data structure with the videoFrame function. (The destination channel must be a VIDEO_IN channel.)
4 When the device driver receives the DVM_FRAME messages that Windows sends in response to videoFrame, it fills the data buffer with information from the frame buffer and updates the VIDEOHDR data structure. Note that the buffer might not have been prepared.
5 When the device driver has filled a data buffer, it returns from the DVM_FRAME message. This returns control back to the client.
6 After the client has finished with the data, it frees the memory used for the data.
Video capture device drivers use the DVM_STREAM messages sent to a VIDEO_IN channel to stream full motion video to the client-application. Your device driver will use the following messages while it is streaming video:
Message | Description |
DVM_STREAM_INIT | Initializes a video input stream. |
DVM_STREAM_ALLOCBUFFER | Lets devices with substantial on-board memory to allocate capture buffers |
DVM_STREAM_FREEBUFFER | Frees buffers allocated in hardware |
DVM_STREAM_PREPAREHEADER | Requests that the driver prepare a data buffer for input. |
DVM_STREAM_ADDBUFFER | Adds a buffer to the video input stream queue. |
DVM_STREAM_START | Begins streaming video input. |
DVM_STREAM_STOP | Ends video input streaming. |
DVM_STREAM_UNPREPAREHEADER | Requests that a driver clean up the preparation previously done on a data buffer. |
DVM_STREAM_FINI | Closes and deallocates a video stream. |
The data transfer model for streaming video input is similar to the model defined for the waveform device drivers. If you have worked with the waveform device drivers, many of the concepts used there will be usable with video capture device drivers.
The following sequence of operations occurs when streaming video data between a video capture device driver and a client-application:
1 The client allocates the memory buffers for the video data.
2 The client initializes the data stream (DVM_STREAM_INIT).
3 The client requests that the driver prepare the data buffers (DVM_STREAM_PREPAREHEADER).
4 The client sends the empty data buffers to the driver (DVM_STREAM_ADDBUFFER).
5 The driver puts the data buffers in its input queue.
6 When the streaming operation begins with DVM_STREAM_START, the driver fills a data buffer and sets the done bit for the data buffer. The driver will then release the buffer from its queue and proceed to fill the next buffer.
7 When the client is ready for data, it uses the done bit or callback to see if the data in the buffer is ready.
8 After the client empties the buffer, it resets the done bit and sends the empty buffer back to the driver for it to add to its queue (DVM_STREAM_ADDBUFFER).
Once the stream starts, the client-application and the video capture driver do not communicate directly. The video capture driver fills the data buffers at the rate specified by the client-application using the frame rate information provided with the DVM_STREAM_INIT message. It fills the buffers without waiting for any synchronization signal from the application as long as buffers are available and it is not paused or stopped by the application. The buffers are filled in the order that the driver receives them from the application. (If the device driver runs out of buffers, it should set an error flag. A client-application can use the DVM_STREAM_GETERROR message to test for this condition.)
The client-application expects the buffers back in the order that it sends them to the device driver. When it is ready for more data, it will check the done bit of the next buffer it expects to receive from the device driver. If the done bit is set, the application continues operation with that buffer. If the done bit is not set, the application will periodically check the done bit while it waits for the buffer.
Streaming continues until it is stopped by the application. The following sequence of operations occurs when the application has finished capturing data:
The DVM_STREAM_INIT message initializes a video device for data streaming. This message must precede all other streaming messages for a channel.
The lParam1 parameter of DVM_STREAM_INIT specifies a far pointer to a VIDEO_STREAM_INIT_PARMS structure and the lParam2 specifies its size in bytes. The VIDEO_STREAM_INIT_PARMS structure has the following members:
typedef struct tag_video_stream_init_parms {
DWORD dwMicroSecPerFrame;
DWORD dwCallback;
DWORD dwCallbackInst;
DWORD dwFlags;
DWORD hVideo;
} VIDEO_STREAM_INIT_PARMS;
The different channels handle the message and data structure in different ways.
For external in channels, DVM_STREAM_INIT enables capture of images into the frame buffer. External in channels should expect this message at any time. They can ignore the dwMicroSecPerFrame, dwCallback, and dwCallbackInst members. The dwFlags member must contain the VIDEO_ALLOWSYNC flag for synchronous devices.
For video in channels, DVM_STREAM_INIT sets the capture rate and callback information. The dwMicroSecPerFrame member specifies the number of microseconds between successive capture frames. The dwCallback member contains the address of a callback function or the handle to a window called during video streaming. (This parameter is set to NULL if a callback function or window is not used.) The callback procedure processes any messages related to the progress of recording. If a callback function address is specified, dwFlags is set to CALLBACK_FUNCTION. If the application has any data to pass to the callback function, it specifies the data in dwCallbackInst. If a callback window handle is specified, dwFlags is set to CALLBACK_WINDOW. Drivers can also use DriverCallback to send a message to a window or callback function.
For external out channels, DVM_STREAM_INIT enables overlay display. External out channels should expect this message at any time. They can ignore the dwMicroSecPerFrame, dwCallback, and dwCallbackInst members. The dwFlags member contains any flags that might affect the external out channel.
All channels return DV_ERR_OK if the message was processed successfully. All channels should return DV_ERR_ALLOCATED if the channel is already allocated or DV_ERR_NOMEM if they are unable to allocate or lock memory.
Because video data buffers must be accessed at interrupt time, the memory allocated for them is subject to the requirements for interrupt driven drivers. Rather than have the client-application prepare the memory before sending data blocks to the driver, the client requests that the driver do the preparation.
Most drivers can respond to the DVM_STREAM_PREPAREHEADER and DVM_STREAM_UNPREPAREHEADER messages) by returning a DV_ERR_UNSUPPORTED error. When your driver returns DV_ERR_UNSUPPORTED, the system will perform the necessary preparation on the data block. This consists of page locking the header and data sections so the driver can access them at interrupt time.
If your device driver does not need the data to be page locked (for example, if you immediately copy the data to an on-card buffer) or if you have additional preparation to do to the buffer, you might respond to these messages yourself instead of having the system handle them. You should respond to both DVM_STREAM_PREPAREHEADER and DVM_STREAM_UNPREPAREHEADER, or to neither.
DVM_STREAM_START starts a video stream. For video in channels, this message begins transferring the contents of the frame buffer to the system supplied buffers. In response to DVM_STREAM_START, your driver should enable the interrupts it needs and begin capturing the images and copying them to the application supplied buffers.
DVM_STREAM_STOP stops a video stream. When a video in channel receives this message, it stops filling buffers and retains any empty buffers remaining in the queue. Your driver can disable any interrupts it needs to capture data, however, it should be prepared to receive the DVM_STREAM_START message to resume capturing data. If data capture has not started, this message has no effect and the device driver returns DV_ERR_OK.
Neither DVM_STREAM_START nor DVM_STEAM_STOP use lParam1 or lParam2. Your driver should return DV_ERR_OK if it processed the message successfully. It should return DV_ERR_NOTSUPPORTED if it does not support the message.
The DVM_STREAM_FINI message terminates data streaming. This should always be the last streaming message received by a channel.
For external in channels, DVM_STREAM_FINI disables capture of images into the frame buffer. External in channels should expect this message at any time. DVM_STREAM_FINI might not have a corresponding DVM_STREAM_INIT message.
For video in channels, DVM_STREAM_FINI finishes data streaming process. Your driver can free any resources that it used to capture data.
For external out channels, DVM_STREAM_FINI disables overlay display. External out channels should expect this message at any time. DVM_STREAM_FINI might not have a corresponding DVM_STREAM_INIT message.
All channels return DV_ERR_OK if the message was processed successfully. The video in channels should return DV_ERR_STILLPLAYING if there are still buffers in its queue.
The client-application uses DVM_STREAM_RESET to stop data streaming and release all buffers. When your driver gets this message it should return to the state set with DVM_STREAM_INIT.
The client-application uses DVM_STREAM_GETERROR to obtain the error status of a channel. The lParam1 and lParam2 parameters point to two DWORDS your driver should use to return error information. Fill the DWORD specified by lParam1 with the value of the most recent error. Typically, the error encountered is DV_ERR_NO_BUFFERS. If your driver has not encountered an error or if it receives this message when a stream is not initialized, set the DWORD to DV_ERR_OK. Fill the DWORD specified by lParam2 with the number of frames dropped because of the error.
After processing this message your driver should reset its error value and count of frames dropped. Drivers that do not have access to interrupts might use this message to trigger buffer processing.
Return DV_ERR_OK if your driver processes the message without an error. If your driver does not support this message, return DV_ERR_NOTSUPPORTED.
Applications use the DVM_STREAM_GETPOSITION message to retrieve the current position of the video in stream. The lParam1 parameter specifies a far pointer to a MMTIME data structure and the lParam2 parameter specifies its size. The MMTIME structure has the following members:
typedef struct mmtime_tag {
UINT wType;
union {
DWORD ms;
DWORD sample;
DWORD cb;
struct {
BYTE hour;
BYTE min;
BYTE sec;
BYTE frame;
BYTE fps;
BYTE dummy;
} smpte;
struct {
DWORD songptrpos;
} midi;
} u;
} MMTIME;
When your device gets DVM_STREAM_POSITION, it should check the wtype member. If your driver does not support the format specified, it specifies its current time format in the member. The application checks the format specified in this member when the message returns.
Video capture drivers typically return time in the millisecond format. Normally, your driver sets the position to zero when streaming starts with DVM_STREAM_START.
Your driver should returns DV_ERR_OK if it processed the message successfully. It can return DV_ERR_PARM1 if the data structure supplied for the format has invalid data or DV_ERR_SIZEFIELD if the data structure is too small.