Tuesday, March 27, 2012

CAPTUREPARMS structure

這是從 C++ Builder 的 Help 所複製出來的文章, 內容是說明在 vfw.h 中所定義的結構資料型態 CAPTUREPARMS structure 每個成員(member) 所代表的意義。
The CAPTUREPARMS structure contains parameters that control the streaming video capture process. This structure is used to get and set parameters that affect the capture rate, the number of buffers to use while capturing, and how capture is terminated.

typedef struct {
DWORD dwRequestMicroSecPerFrame;
BOOL fMakeUserHitOKToCapture;
UINT wPercentDropForError;
BOOL fYield;
DWORD dwIndexSize;
UINT wChunkGranularity;
BOOL fUsingDOSMemory;
UINT wNumVideoRequested;
BOOL fCaptureAudio;
UINT wNumAudioRequested;
UINT vKeyAbort;
BOOL fAbortLeftMouse;
BOOL fAbortRightMouse;
BOOL fLimitEnabled;
UINT wTimeLimit;
BOOL fMCIControl;
BOOL fStepMCIDevice;
DWORD dwMCIStartTime;
DWORD dwMCIStopTime;
BOOL fStepCaptureAt2x;
UINT wStepCaptureAverageFrames;
DWORD dwAudioBufferSize;
BOOL fDisableWriteCache;
UINT AVStreamMaster;
} CAPTUREPARMS;

Members

dwRequestMicroSecPerFrame

Requested frame rate, in microseconds. The default value is 66667, which corresponds to 15 frames per second.

fMakeUserHitOKToCapture

User-initiated capture flag. If this member is TRUE, AVICap displays a dialog box prompting the user to initiate capture. The default value is FALSE.

wPercentDropForError

Maximum allowable percentage of dropped frames during capture. Values range from 0 to 100. The default value is 10.

fYield

Yield flag. If this member is TRUE, the capture window spawns a separate background thread to perform step and streaming capture. The default value is FALSE.

Applications that set this flag must handle potential reentry issues because the controls in the application are not disabled while capture is in progress.

dwIndexSize

Maximum number of index entries in an AVI file. Values range from 1800 to 324,000. If set to 0, a default value of 34,952 (32K frames plus a proportional number of audio buffers) is used.

Each video frame or buffer of waveform-audio data uses one index entry. The value of this entry establishes a limit for the number of frames or audio buffers that can be captured.

wChunkGranularity

Logical block size, in bytes, of an AVI file. The value 0 indicates the current sector size is used as the granularity.

fUsingDOSMemory

Not used in Win32 applications.

wNumVideoRequested

Maximum number of video buffers to allocate. The memory area to place the buffers is specified with fUsingDOSMemory. The actual number of buffers allocated might be lower if memory is unavailable.

fCaptureAudio

Capture audio flag. If this member is TRUE, audio is captured during streaming capture. This is the default value if audio hardware is installed.

wNumAudioRequested

Maximum number of audio buffers to allocate. The maximum number of buffers is 10.

vKeyAbort

Virtual keycode used to terminate streaming capture. The default value is VK_ESCAPE. You must call the RegisterHotKey function before specifying a keystroke that can abort a capture session.

You can combine keycodes that include CTRL and SHIFT keystrokes by using the logical OR operator with the keycodes for CTRL (0x8000) and SHIFT (0x4000).

fAbortLeftMouse

Abort flag for left mouse button. If this member is TRUE, streaming capture stops if the left mouse button is pressed. The default value is TRUE.

fAbortRightMouse

Abort flag for right mouse button. If this member is TRUE, streaming capture stops if the right mouse button is pressed. The default value is TRUE.

fLimitEnabled

Time limit enabled flag. If this member is TRUE, streaming capture stops after the number of seconds in wTimeLimit has elapsed. The default value is FALSE.

wTimeLimit

Time limit for capture, in seconds. This parameter is used only if fLimitEnabled is TRUE.

fMCIControl

MCI device capture flag. If this member is TRUE, AVICap controls an
MCI-compatible video source during streaming capture. MCI-compatible video sources include VCRs and laserdiscs.

fStepMCIDevice

MCI device step capture flag. If this member is TRUE, step capture using an MCI device as a video source is enabled. If it is FALSE, real-time capture using an MCI device is enabled. (If fMCIControl is FALSE, this member is ignored.)

dwMCIStartTime

Starting position, in milliseconds, of the MCI device for the capture sequence. (If fMCIControl is FALSE, this member is ignored.)

dwMCIStopTime

Stopping position, in milliseconds, of the MCI device for the capture sequence. When this position in the content is reached, capture ends and the MCI device stops. (If fMCIControl is FALSE, this member is ignored.)

fStepCaptureAt2x

Double-resolution step capture flag. If this member is TRUE, the capture hardware captures at twice the specified resolution. (The resolution for the height and width is doubled.)

Enable this option if the hardware does not support hardware-based decimation and you are capturing in the RGB format.

wStepCaptureAverageFrames

Number of times a frame is sampled when creating a frame based on the average sample. A typical value for the number of averages is 5.

dwAudioBufferSize

Audio buffer size. If the default value of zero is used, the size of each buffer will be the maximum of 0.5 seconds of audio or 10K bytes.

fDisableWriteCache

Not used in Win32 applications.

AVStreamMaster

Indicates whether the audio stream controls the clock when writing an AVI file. If this member is set to AVSTREAMMASTER_AUDIO, the audio stream is considered the master stream and the video stream duration is forced to match the audio duration. If this member is set to AVSTREAMMASTER_NONE, the durations of audio and video streams can differ.

Remarks

The WM_CAP_GET_SEQUENCE_SETUP message or capCaptureGetSetup macro is used to retrieve the current capture parameters. The WM_CAP_SET_SEQUENCE_SETUP message or capCaptureSetSetup macro is used to set the capture parameters.
延伸閱讀: 取得與設定錄影參數

Monday, March 19, 2012

TCapStatus structure

CAPSTATUS
The CAPSTATUS structure defines the current state of the capture window.

typedef struct {
UINT uiImageWidth;
UINT uiImageHeight;
BOOL fLiveWindow;
BOOL fOverlayWindow;
BOOL fScale;
POINT ptScroll;
BOOL fUsingDefaultPalette;
BOOL fAudioHardware;
BOOL fCapFileExists;
DWORD dwCurrentVideoFrame;
DWORD dwCurrentVideoFramesDropped;
DWORD dwCurrentWaveSamples;
DWORD dwCurrentTimeElapsedMS;
HPALETTE hPalCurrent;
BOOL fCapturingNow;
DWORD dwReturn;
UINT wNumVideoAllocated;
UINT wNumAudioAllocated;
} CAPSTATUS;

Members

 uiImageWidth

Image width, in pixels.

 uiImageHeight 

Image height, in pixels

 fLiveWindow 

Live window flag. The value of this member is TRUE if the window is displaying video using the preview method.

 fOverlayWindow 

Overlay window flag. The value of this member is TRUE if the window is displaying video using hardware overlay.

 fScale

Input scaling flag. The value of this member is TRUE if the window is scaling the input video to the client area when displaying video using preview. This parameter has no effect when displaying video using overlay.

 ptScroll

The x- and y-offset of the pixel displayed in the upper left corner of the client area of the window.

 fUsingDefaultPalette

Default palette flag. The value of this member is TRUE if the capture driver is using its default palette.

 fAudioHardware

Audio hardware flag. The value of this member is TRUE if the system has waveform-audio hardware installed.

 fCapFileExists

Capture file flag. The value of this member is TRUE if a valid capture file has been generated.

 dwCurrentVideoFrame

Number of frames processed during the current (or most recent) streaming capture. This count includes dropped frames.

 dwCurrentVideoFramesDropped

Number of frames dropped during the current (or most recent) streaming capture. Dropped frames occur when the capture rate exceeds the rate at which frames can be saved to file. In this case, the capture driver has no buffers available for storing data. Dropping frames does not affect synchronization because the previous frame is displayed in place of the dropped frame.

 dwCurrentWaveSamples

Number of waveform-audio samples processed during the current (or most recent) streaming capture.

 dwCurrentTimeElapsedMS

Time, in milliseconds, since the start of the current (or most recent) streaming capture.

 hPalCurrent

Handle to current palette.

 fCapturingNow

Capturing flag. The value of this member is TRUE when capturing is in progress.

 dwReturn

Error return values. Use this member if your application does not support an error callback function.

 wNumVideoAllocated

Number of video buffers allocated. This value might be less than the number specified in the wNumVideoRequested member of the CAPTUREPARMS structure.

 wNumAudioAllocated

Number of audio buffers allocated. This value might be less than the number specified in the wNumAudioRequested member of the CAPTUREPARMS structure.

Remarks

Because the state of a capture window changes in response to various messages, an application should update the information in this structure whenever it needs to enable menu items, determine the actual state of the capture window, or call the video format dialog box. If the application yields during streaming capture, this structure returns the progress of the capture in the dwCurrentVideoFrame, dwCurrentVideoFramesDropped, dwCurrentWaveSamples, and dwCurrentTimeElapsedMS members. Use the WM_CAP_GET_STATUS message or capGetStatus macro to update the contents of this structure.

VFW: 視訊擷取視窗狀態

capGetStatus
The capGetStatus macro retrieves the status of the capture window. You can use this macro or explicitly call the WM_CAP_GET_STATUS message.

BOOL capGetStatus(
hwnd,
s,
wSize
);

Parameters

hwnd Handle to a capture window.

s Pointer to a CAPSTATUS structure.

wSize Size, in bytes, of the structure referenced by s.

Return Values

Returns TRUE if successful or FALSE if the capture window is not connected to a capture driver.

Remarks

The CAPSTATUS structure contains the current state of the capture window. Since this state is dynamic and changes in response to various messages, the application should initialize this structure after sending the capDlgVideoFormat macro and whenever it needs to enable menu items or determine the actual state of the window.