Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide
Previous Contents Index

videoStreamFini

 Name videoStreamFini --- Terminate streaming from the specified device channel Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamFini(HVIDEO hVideo)
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoStreamFini function terminates streaming from the specified device channel. If there are buffers sent with the videoStreamAddBuffer function that have not been returned to the application, this operation will fail. Use the videoStreamReset function to mark all pending buffers as done. Then, call the videoStreamFini function to terminate streaming from the device channel.

Each call to the videoStreamInit function must be matched with a call to the videoStreamFini function.

Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_STILLPLAYING There are buffers still in the queue.
See Also videoClose , videoStreamInit

videoStreamGetError

 Name videoStreamGetError --- Return the error most recently encountered Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamGetError(HVIDEO hVideo, 
                             LPDWORD lpdwErrorID, 
                             LPDWORD lpdwErrorValue);
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

LPDWORD lpdwErrorID
Specifies a pointer to the DWORD to be filled with the error ID.

LPDWORD lpdwErrorValue
Specifies a pointer to the DWORD to be filled with the number of frames skipped.

Description

The videoStreamGetError function returns the error most recently encountered. While streaming video data, a video capture driver can fill buffers faster than the client application can save the buffers to disk. In this case, the DV_ERR_NO_BUFFERS error code is returned in the lpdwErrorID argument, and a count of the number of video frames missed is contained in the lpdwErrorValue argument. If there is no error, the DV_ERR_OK code is returned in the lpdwErrorID argument.
Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_NOTSUPPORTED The function is not supported.
See Also videoOpen

videoStreamGetPosition

 Name videoStreamGetPosition --- Retrieve current position of the specified video device channel Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamGetPosition(HVIDEO hVideo, 
                                LPMMTIME lpInfo, 
                                DWORD dwSize);
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

LPMMTIME lpInfo
Specifies a pointer to an MMTIME data structure.

The MMTIME data structure must be allocated with the mmeAllocMem function before being passed to the videoStreamGetPosition function. See Chapter 2 for descriptions of these memory allocation functions.

DWORD dwSize
Specifies the size of the MMTIME data structure.

Description

The videoStreamGetPosition function retrieves the current position of the specified video device channel. The position is set to zero when streaming is started with the videoStreamStart function.

Before using the videoStreamGetPosition function, set the wType field of the MMTIME data structure to indicate the desired time format. After the videoStreamGetPosition function returns, check the wType field to determine if the time format is supported. If not, the wType field will specify an alternate format. Typically, the sample number time format is provided. See Section 2.3 for more information about the MMTIME data structure.

Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
See Also None.

videoStreamInit

 Name videoStreamInit --- Initialize a video device channel for streaming Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamInit(HVIDEO hVideo, 
                         DWORD dwMicroSecPerFrame, 
                         void  (*dwCallback) (), 
                         DWORD dwCallbackInstance, 
                         DWORD dwFlags);
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

DWORD dwMicroSecPerFrame
Specifies the number of microseconds between frames.

void (*dwCallback) ()
Specifies the address of a callback function called during video streaming. The callback function processes messages related to the progress of video streaming.

DWORD dwCallbackInstance
Specifies user instance data passed to the callback function.

DWORD dwFlags
Specifies flags for opening the device channel. The dwCallback function is required for the VIDEO_IN and VIDEO_OUT channels. Thus, dwFlags is required to contain CALLBACK_FUNCTION. The following flag is defined:

CALLBACK_FUNCTION
If this flag is specified, the dwCallback argument is a callback procedure address.

Description

The videoStreamInit function initializes a video device channel for streaming. An application must specify a callback function in a call to the videoStreamInit function in order to be notified about the state of the video capture or playback buffers.
Callback 


 
void CALLBACK videoCallbackFunction(HVIDEO hVideo, 
                                    DWORD wMsg, 
                                    DWORD dwInstance, 
                                    LPARAM lParam1, 
                                    LPARAM lParam2);

The videoCallbackFunction function is a placeholder for the function name supplied by the application. Callback Arguments HVIDEO hVideo
Specifies a handle to a video device channel associated with the callback function.

DWORD wMsg
Specifies the video streaming message. The following messages are defined:

MM_DRVM_OPEN
Sent when the device channel is initialized using the videoStreamInit function.

MM_DRVM_CLOSE
Sent when streaming is terminated using the videoStreamFini function.

MM_DRVM_DATA
Sent when a buffer of image data is available.

MM_DRVM_ERROR
Sent when an error occurs.

DWORD dwInstance
Specifies the user instance data specified with the videoStreamInit function.

LPARAM lParam1
Specifies an argument for the message and is only valid while the callback function is executing.

For the MM_DRVM_OPEN, MM_DRVM_CLOSE, and MM_DRVM_ERROR messages, this argument is not used. For the MM_DRVM_DATA message, this argument specifies a pointer to a VIDEOHDR data structure identifying the completed data block. The VIDEOHDR data structure address is only valid while the callback function is executing; the address of the VIDEOHDR data structure will not be the same as the address of the VIDEOHDR data structure passed into the videoStreamAddBuffer function. The contents of the VIDEOHDR data structure will be modified to reflect the result of the operation.

LPARAM lParam2
Specifies an argument for the message. This argument is not used. Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
DV_ERR_ALLOCATED The specified resource is already allocated.
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_NOMEM Unable to allocate or lock memory.
DV_ERR_PARAM1 The specified callback function is invalid. Callbacks are required.
See Also videoClose , videoOpen , videoStreamFini

videoStreamPrepareHeader

 Name videoStreamPrepareHeader ---Prepare a buffer for video streaming Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamPrepareHeader(HVIDEO hVideo, 
                                  LPVIDEOHDR lpvideoHdr, 
                                  DWORD dwSize);
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

LPVIDEOHDR lpvideoHdr
Specifies a pointer to a VIDEOHDR data structure that identifies the buffer to be prepared.

The VIDEOHDR data structure must be allocated with the mmeAllocMem function. The data buffer pointed to by its lpData field or the data buffers pointed to by its lpData2 field must be allocated with the mmeAllocBuffer or mmeAllocBufferAndGetShminfo function. See Chapter 2 for descriptions of these memory allocation functions.

DWORD dwSize
Specifies the size of the VIDEOHDR data structure.

Description

The videoStreamPrepareHeader function prepares a buffer for video streaming.

Use the videoStreamPrepareHeader function after the videoStreamInit function or after the videoStreamReset function to prepare the data buffers for streaming data.

To determine the size of the buffer needed for capturing or playing back data, use the videoConfigure function. Set the dwFlags argument to:

(VIDEO_CONFIGURE_GET | VIDEO_CONFIGURE_MIN)

The size is returned in the biSizeImage field of the BITMAPINFOHEADER data structure.

Preparing a header that has already been prepared has no effect, and the function returns the DV_ERR_OK code.

Extensions The VIDEOHDR data structure has been extended by three fields: lpData2, dwBufferLength2, and dwBytesUsed2 to support dual buffers for use with the video option modules that support dual buffering.

See Section 4.4.2 and Section 4.5 for more information about the VIDEOHDR data structure and using dual buffers.

Compaq has extended the Microsoft video and ICM (Installable Compression Manager) interfaces to provide for memory optimization. See Section 1.5.8 for more information.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
DV_ERR_BADFORMAT The specified format cannot be set.
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_NOMEM Unable to allocate or lock memory.
See Also videoStreamUnprepareHeader

videoStreamReset

 Name videoStreamReset --- Stop video streaming and reset current position Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamReset(HVIDEO hVideo)
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoStreamReset function stops streaming on the specified video device channel and resets the current position to zero. All pending buffers are marked as done and are returned to the calling application.
Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
See Also videoClose , videoStreamAddBuffer , videoStreamStart , videoStreamStop

videoStreamStart

 Name videoStreamStart --- Start video streaming Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamStart(HVIDEO hVideo)
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoStreamStart function starts streaming on the specified video device channel.

If buffers are added before calling videoStreamStart , any of the error conditions described for videoStreamAddBuffer may be returned from the videoStreamStart call. Buffers added before the videoStreamStart may not be validated until videoStreamStart is called; internally to the device, validation might be performed by calling videoStreamAddBuffer from videoStreamStart and thus errors from videoStreamAddBuffer might be returned during a call to videoStreamStart .

Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
See Also videoClose , videoStreamAddBuffer , videoStreamReset , videoStreamStop

videoStreamStop

 Name videoStreamStop --- Stop video streaming Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamStop(HVIDEO hVideo)
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

Description

The videoStreamStop function stops streaming on a video channel. If there are any buffers in the queue, the dwFlags field in the VIDEOHDR data structure for the current buffer will be set to VHDR_DONE, and the dwBytesUsed or dwBytesUsed2 fields in the VIDEOHDR data structure will contain the actual length of the data captured or output. Any buffers that were previously queued and not returned to the client via a callback will be held in the queue until the functions videoStreamStart or videoStreamReset are called.

Calling this function when the channel is not started has no effect, and the function returns DV_ERR_OK.

Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns the following error code:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
See Also videoStreamReset , videoStreamStart

videoStreamUnprepareHeader

 Name videoStreamUnprepareHeader --- Clean up the preparation performed by the videoStreamPrepareHeader function Syntax 


#include <mme/mme_api.h> 
 
MMRESULT videoStreamUnprepareHeader(HVIDEO hVideo, 
                                    LPVIDEOHDR lpvideoHdr, 
                                    DWORD dwSize);
Arguments HVIDEO hVideo
Specifies a handle to a video device channel.

LPVIDEOHDR lpvideoHdr
Specifies a pointer to a VIDEOHDR data structure identifying the data buffer to be cleaned up.

DWORD dwSize
Specifies the size of the VIDEOHDR data structure.

Description

The videoStreamUnprepareHeader function cleans up the preparation performed by the videoStreamPrepareHeader function. The videoStreamUnprepareHeader function is the complementary function to the videoStreamPrepareHeader function.

Call the videoStreamUnprepareHeader function before freeing the data buffer with the mmeFreeBuffer function. After passing a buffer to the device driver with the videoStreamAddBuffer function, wait until the driver is finished with the buffer before calling the videoStreamUnprepareHeader function. Unpreparing a buffer that has not been prepared has no effect, and the function returns the DV_ERR_OK error code.

Extensions None.

Return Values

1
Returns DV_ERR_OK if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_STILLPLAYING There are buffers still in the queue.
See Also videoStreamPrepareHeader

4.8 Video Capture and Playback Return Values

This section presents the video capture and playback return values or error codes. Table 4-2 lists the codes that can be returned by one or more of the video capture and playback functions.

Table 4-2 Video Capture and Playback Error Codes
Error Code Description
DV_ERR_ALLOCATED The specified resource is already allocated.
DV_ERR_BADDEVICEID The specified device ID is out of range.
DV_ERR_BADFORMAT The specified format cannot be set.
DV_ERR_BADERRNUM The specified error number is out of range.
DV_ERR_CREATE_PALETTE Could not create palette.
DV_ERR_INVALHANDLE The specified device handle is invalid.
DV_ERR_OK Success.
DV_ERR_NOMEM Unable to allocate or lock memory.
DV_ERR_NONSPECIFIC The driver failed to close the channel.
DV_ERR_NOTSUPPORTED The function is not supported.
DV_ERR_PARAM1 The specified parameter is invalid.
DV_ERR_STILLPLAYING There are buffers still in the queue.
DV_ERR_UNPREPARED The VIDEOHDR data structure has not been prepared.

Previous Next Contents Index