capGetVideoFormat macro

透過 VFW 所提供的 capGetVideoFormat 函式, 可以取得視訊畫面資料的寬、高、一個像素(pixel)由幾個位元組成及視訊畫面資料是否經過壓縮... 等等。如果想要修改視訊擷取視窗中的畫面內容, 這些資料就變成相當重要。

The capGetVideoFormat macro retrieves a copy of the video format in use. You can use this macro or explicitly call the WM_CAP_GET_VIDEOFORMAT message.

DWORD capGetVideoFormat(
hwnd,
psVideoFormat,
wSize
);

Parameters

hwnd

Handle to a capture window.

psVideoFormat

Pointer to a BITMAPINFO structure. You can also specify NULL to retrieve the number of bytes needed by BITMAPINFO.

wSize

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

Return Values

Returns the size, in bytes, of the video format or zero if the capture window is not connected to a capture driver. For video formats that require a palette, the current palette is also returned.

Remarks

Because compressed video formats vary in size requirements applications must first retrieve the size, then allocate memory, and finally request the video format data.

capCaptureStop macro

結束連續視訊串流擷取。

The capCaptureStop macro stops the capture operation. You can use this macro or explicitly send the WM_CAP_STOP message.

In step frame capture, the image data that was collected before this message was sent is retained in the capture file. An equivalent duration of audio data is also retained in the capture file if audio capture was enabled.

BOOL capCaptureStop(
hwnd
);
Parameters

hwnd

Handle to a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this message. Use the capCaptureAbort macro to abandon the current capture operation.

capCaptureAbort macro

中止錄影動作。

The capCaptureAbort macro stops the capture operation. You can use this macro or explictly send the WM_CAP_ABORT message.

BOOL capCaptureAbort(
hwnd
);

Parameters

hwnd

Handle to a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The capture operation must yield to use this macro.

In the case of step capture, the image data collected up to the point of the capCaptureAbort macro will be retained in the capture file, but audio will not be captured.

Use the capCaptureStop macro to halt step capture at the current position, and then capture audio.

capFileSetCaptureFile macro

若要將視訊擷取視窗的視訊、音訊內容儲存成檔案, 可以先使用 capFileSetCaptureFile macro 設定所要儲存的檔案名稱。若沒有預先設定, 檔案名稱則內定為 C:\CAPTURE.AVI。

The capFileSetCaptureFile macro names the file used for video capture. You can use this macro or explicitly call the WM_CAP_FILE_SET_CAPTURE_FILE message.

BOOL capFileSetCaptureFile(
hwnd,
szName
);

Parameters

hwnd

Handle to a capture window.

szName

Pointer to the null-terminated string that contains the name of the capture file to use.

Return Values

Returns TRUE if successful or FALSE if the filename is invalid or if streaming or single-frame capture is in progress.

Remarks

This message stores the filename in an internal structure. It does not create, allocate, or open the specified file. The default capture filename is C:\CAPTURE.AVI.

capFileGetCaptureFile macro

透過 capFileGetCaptureFile macro, 可以得知所錄影的視訊內容, 將會被儲存的檔案名稱。如果使用者沒有透過 capFileSetCaptureFile macro 重新設定過, 內定的名稱為 C:\CAPTURE.AVI。

The capFileGetCaptureFile macro returns the name of the current capture file. You can use this macro or explicitly call the WM_CAP_FILE_GET_CAPTURE_FILE message.

BOOL capFileGetCaptureFile(
hwnd,
szName,
wSize
);

Parameters

hwnd

Handle to a capture window.

szName

Pointer to an application-defined buffer used to return the name of the capture file as a null-terminated string.

wSize

Size, in bytes, of the application-defined buffer referenced by szName.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

The default capture filename is C:\CAPTURE.AVI.

capCaptureSequence macro

使用　capCaptureSequence macro　可以將視訊擷取視窗中的視訊與音訊內容儲存成一個 AVI 檔案, 檔案名稱則可以是透過 capFileSetCaptureFile macro 事先設定, 若沒有設定檔案名稱, 則內定為 C:\CAPTURE.AVI。

The capCaptureSequence macro initiates streaming video and audio capture to a file. You can use this macro or explicitly send the WM_CAP_SEQUENCE message.

BOOL capCaptureSequence(
hwnd
);


Parameters

hwnd

Handle of a capture window.

Return Values

Returns TRUE if successful or FALSE otherwise.
If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks

If you want to alter the parameters controlling streaming capture, use the capCaptureSetSetup macro prior to starting the capture.
By default, the capture window does not allow other applications to continue running during capture. To override this, either set the fYield member of the CAPTUREPARMS structure to TRUE, or install a yield callback function.
During streaming capture, the capture window can optionally issue notifications to your application of specific types of conditions. To install callback procedures for these notifications, use the following macros:

capSetCallbackOnError
capSetCallbackOnStatus
capSetCallbackOnVideoStream
capSetCallbackOnWaveStream
capSetCallbackOnYield

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.

延伸閱讀: 取得與設定錄影參數

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.

VFW: 視訊參數對話盒 Video Dialog Box

一般來說, 硬體製造廠商會提供驅動程式(driver)供使用者將硬體裝置安裝到電腦。視訊裝置也是一樣, 所安裝的驅動程式還會提供一些預先寫好的視訊參數對話盒, 供程式設計師直接呼叫, 以修改視訊裝置的相關參數。不同的廠商所提供的視訊參數對話盒不一定相同, 甚至有些廠商並不一定有提供視訊參數對話盒, 因此, 程式設計師在呼叫視訊參數對話盒之前, 可以先透過 capDriverGetCaps 函式, 先取得視訊裝置驅動程式的效能, 確認之後再進行呼叫。

視訊參數對話盒一共有四種, 分別是:
　1. 視訊來源對話盒 (Video Source Dialog)
　2. 視訊格式對話盒 (Video Format Dialog)
　3. 視訊顯示對話盒 (Video Display Dialog)
　4. 視訊壓縮對話盒 (Video Compression Dialog)

接下來我們將分別介紹各種視訊參數對話盒的呼叫函式。

　1. 視訊來源對話盒 (Video Source Dialog Box)

　capDlgVideoSource

The capDlgVideoSource macro displays a dialog box in which the user can control the video source. The Video Source dialog box might contain controls that select input sources; alter the hue, contrast, brightness of the image; and modify the video quality before digitizing the images into the frame buffer. You can use this macro or explicitly send the WM_CAP_DLG_VIDEOSOURCE message.

BOOL capDlgVideoSource(
hwnd
);

Parameters

　hwnd

　　Handle to a capture window.

Return Values

　Returns TRUE if successful or FALSE otherwise.

Remarks

The Video Source dialog box is unique for each capture driver. Some capture drivers might not support a Video Source dialog box. Applications can determine if the capture driver supports this message by checking the fHasDlgVideoSource member of the CAPDRIVERCAPS structure.

VFW: 視訊資料表頭結構

在 vfw.h 中第 3148 行起, 定義了視訊資料表頭結構(video data block header), 如下:

/* video data block header */
typedef struct videohdr_tag {
LPBYTE lpData; /* pointer to locked data buffer */
DWORD dwBufferLength; /* Length of data buffer */
DWORD dwBytesUsed; /* Bytes actually used */
DWORD dwTimeCaptured; /* Milliseconds from start of stream */
DWORD_PTR dwUser; /* for client's use */
DWORD dwFlags; /* assorted flags (see defines) */
DWORD_PTR dwReserved[4]; /* reserved for driver */
} VIDEOHDR, NEAR *PVIDEOHDR, FAR *LPVIDEOHDR;

使用 typedef 的宣告方式, 將 videohdr_tag 這個新的資料形態取了三個別名, 分別是 VIDEOHDR, NEAR *PVIDEOHDR 與 FAR *LPVIDEOHDR。

lpData 紀錄視訊資料緩衝區的位址, 透過此資料成員便可以直接存取視訊影像資料。

dwBufferLength 紀錄 lpData 所指向的視訊資料緩衝區的容量大小。

dwByteUsed 紀錄視訊資料緩衝區已經被使用了多少位元組。

dwTimeCaptured 紀錄影音串流擷取已使用的時間(毫秒 ms)。

dwUser 紀錄視訊擷取視窗關聯的使用者自訂資料。

dwFlags 紀錄視訊資料表頭旗標, 其定義就是在 vfw.h 中, 第 3158 行後所定義的, 如下:

/* dwFlags field of VIDEOHDR */
#define VHDR_DONE 0x00000001 /* Done bit */
#define VHDR_PREPARED 0x00000002
/* Set if this header has been prepared */
#define VHDR_INQUEUE 0x00000004 /* Reserved for driver */
#define VHDR_KEYFRAME 0x00000008 /* Key Frame */
#define VHDR_VALID 0x0000000F /* valid flags */ /* ;Internal */
　

VFW: 取得與設定錄影參數

攝影機錄影期間, 必須針對需求設定相關攝影參數, 這些參數在 vfw.h 之中, 宣告一個資料型態來儲存這些參數。

typedef struct tagCaptureParms {
　DWORD dwRequestMicroSecPerFrame;
　　　　　　　　　　 // Requested capture rate
　BOOL fMakeUserHitOKToCapture; // Show "Hit OK to cap" dlg?
　UINT wPercentDropForError; // Give error msg if > (10%)
　BOOL fYield; // Capture via background task?
　DWORD dwIndexSize; // Max index size in frames (32K)
　UINT wChunkGranularity; // Junk chunk granularity (2K)
　BOOL fUsingDOSMemory; // Use DOS buffers?
　UINT wNumVideoRequested; // # video buffers, If 0, autocalc
　BOOL fCaptureAudio; // Capture audio?
　UINT wNumAudioRequested; // # audio buffers, If 0, autocalc
　UINT vKeyAbort; // Virtual key causing abort
　BOOL fAbortLeftMouse; // Abort on left mouse?
　BOOL fAbortRightMouse; // Abort on right mouse?
　BOOL fLimitEnabled; // Use wTimeLimit?
　UINT wTimeLimit; // Seconds to capture
　BOOL fMCIControl; // Use MCI video source?
　BOOL fStepMCIDevice; // Step MCI device?
　DWORD dwMCIStartTime; // Time to start in MS
　DWORD dwMCIStopTime; // Time to stop in MS
　BOOL fStepCaptureAt2x; // Perform spatial averaging 2x
　UINT wStepCaptureAverageFrames;
　　　　　　　　　　// Temporal average n Frames
　DWORD dwAudioBufferSize; // Size of audio bufs (0 = default)
　BOOL fDisableWriteCache; // Attempt to disable write cache
　UINT AVStreamMaster; // Which stream controls length?
} CAPTUREPARMS, *PCAPTUREPARMS, FAR *LPCAPTUREPARMS;

因此, 我們在程式中可以如下宣告一個變數 s,

tagCaptureParms s;

然後, 我們就可以透過 &s 當作為呼叫 VFW SDK 相關函數的參數, 了解目前視訊系統的攝影參數設定為何? 一般來說, 一些我們比較常用到的攝影參數為:

• 指定視訊畫面的擷取速率
• 指定分派影像緩衝區數目
• 選擇是否'擷取聲音
• 指定視訊串流擷取時間長短
• 指定擷取時間是否使用 MCI 裝置
• 指定鍵盤或滑鼠控制來終止擷取
  

在 VFW SDK 中, 透過 capCaptureGetSetup 可以知道目前的錄影參數的設定為何?

The capCaptureGetSetup macro retrieves the current settings of the streaming capture parameters.

BOOL capCaptureGetSetup(
　hwnd,
　s,
　wSize
　);

Parameters
hwnd　Handle of a capture window.
s　Address of a CAPTUREPARMS structure.
wSize　Size, in bytes, of the structure referenced by s.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

知道了錄影參數的設定情形後, 我們也可以透過 capCaptureSetSetup 來改變錄影參數的設定:

The capCaptureSetSetup macro sets the configuration parameters used with streaming capture.

BOOL capCaptureSetSetup(
　hwnd,
　s,
　wSize
　);

Parameters
hwnd　Handle of a capture window.
s　Address of a CAPTUREPARMS structure.
wSize　Size, in bytes, of the structure referenced by s.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
For information about the parameters used to control streaming capture, see the CAPTUREPARMS structure.

延伸閱讀: C++ Builder's Help 中的 CAPTUREPARMS structure

VFW: 靜態影像擷取

VFW SDK 所提供的擷取靜態影像方式是先抓取單一視訊畫面 ( frame ), 將其存入記憶體緩衝區中, 接下來你可以選擇要將存到剪貼簿中, 或是直接存成一張點陣圖檔 ( .BMP )。

抓取單一視訊畫面時, 依照不同需求, 可以使用 capGrabFrame 選擇讓原先動態的視訊畫面靜止, 或是用 capGrabFrameNoStop 不讓畫面靜止。靜止的影像可以讓我們清楚地看清抓取的視訊畫面為何, 如果要讓原先的擷取視窗恢復動態顯示, 則是必須重新 設定顯示模式 才行。

The capGrabFrame macro retrieves and displays a single frame from the capture driver. After capture, overlay and preview are disabled.

BOOL capGrabFrame(
　hwnd
　);

Parameters
hwnd Handle of a capture window.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
For information about installing callback functions, see the capSetCallbackOnError and capSetCallbackOnFrame macros.

因為必須告知要抓取哪一個視訊視窗, 所以函數的傳入值 ( parameter ) 就是該視窗的代碼 ( handle)。而傳回值 ( return value ) 就是告知我們是否成功捉取畫面。至於抓取畫面後的後續動作, 還可以使用回呼函數 ( callback function ) 來執行。

The capGrabFrameNoStop macro fills the frame buffer with a single uncompressed frame from the capture device and displays it. Unlike with the capGrabFrame macro, the state of overlay or preview is not altered by this message.

BOOL capGrabFrameNoStop(
　hwnd
　);

Parameters
hwnd Handle of a capture window.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
For information about installing callback functions, see the capSetCallbackOnError and capSetCallbackOnFrame macros.

以點陣圖格式 ( device independent bitmap, DIB ) 放入緩衝區的視訊畫面, 可以透過放到剪貼簿的方式 (capEditCopy) 讓別的應用程式使用。

The capEditCopy macro copies the contents of the video frame buffer and associated palette to the clipboard.

BOOL capEditCopy(
　hwnd
　);

Parameters
hwnd Handle of a capture window.

Return Values
Returns TRUE if successful or FALSE otherwise.

我們也可以使用 capFileSaveDIB 直接將緩衝區中畫面存成點陣圖檔 ( .BMP )。

The capFileSaveDIB macro copies the current frame to a DIB file.

BOOL capFileSaveDIB(
　hwnd,
　szName
);

Parameters
hwnd Handle of a capture window.
szName Address of the null-terminated string that contains the name of the destination DIB file.

Return Values
Returns TRUE if successful or FALSE otherwise. If an error occurs and an error callback function is set using the capSetCallbackOnError macro, the error callback function is called.

Remarks
If the capture driver supplies frames in a compressed format, this call attempts to decompress the frame before writing the file.

注意: 輸入參數 szName 變數名稱前置的 sz 告訴我們這是一個 null-terminated string。而要傳入的正是該 string 的記憶體位址 ( address )。因此, 若是我們在 BCB 中, 要用一個 TSavePictureDialog 類別的物件要讓使用者輸入檔名, 我們在程式中則是要將該物件的檔名屬性 ( TSavePictureDialog::FileName ) 中的檔名位址指定給 capFileSaveDIB 函數。假設該物件的名稱為 SavePictureDialog1, 而檔名的位址為: &SavePictureDialog1->FileName[1]。

範例程式:
　if ( SavePictureDialog1->Execute() )
　　{
　　capFileSaveDIB(hwndVideo,&(SavePictureDialog1->FileName[1]));
　　}
　

VFW: 調整視訊畫面大小

調整視訊畫面大小主要有兩個步驟:
1. 使用VFW SDK 所提供的 capPreviewScale 函數設定畫面大小是否隨著視窗大小變化。
2. 使用 Win32 API 的 MoveWindow 函數來調整視訊擷取視窗的大小。

在 Preview 的顯示模式下, VFW SDK 提供 capPreviewScale 函數來允許視訊畫面大小隨著視窗大小變化而調整。

The capPreviewScale macro enables or disables scaling of the preview video images. If scaling is enabled, the captured video frame is stretched to the dimensions of the capture window.

BOOL capPreviewScale(
　hwnd,
　f
　);

Parameters
hwnd Handle of a capture window.
f Preview scaling flag.
Specify TRUE for this parameter to stretch preview frames to the size of the
capture window or FALSE to display them at their natural size.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
Scaling preview images controls the immediate presentation of captured frames within the capture window. It has no effect on the size of the frames saved to file. Scaling has no effect when using overlay to display video in the frame buffer.

設定擷取畫面隨著擷取視窗的位置, 大小而調整後, 我們就可以使用 Win32 API 所提供的 MoveWindow 函數來調整視窗, 達到調整視訊擷取畫面的目的

The MoveWindow function changes the position and dimensions of the specified window. For a top-level window, the position and dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-left corner of the parent window's client area.

BOOL MoveWindow(
　HWND hWnd, 　// handle of window
　int X,　　　　　// horizontal position
　int Y,　　　　　// vertical position
　int nWidth,　　// width
　int nHeight, 　　// height
　BOOL bRepaint // repaint flag
　);

Parameters
hWnd Identifies the window.
X Specifies the new position of the left side of the window.
Y Specifies the new position of the top of the window.
nWidth Specifies the new width of the window.
nHeight Specifies the new height of the window.
bRepaint Specifies whether the window is to be repainted. If this parameter is TRUE, the window receives a WM_PAINT message. If the parameter is FALSE, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of moving a child window. If this parameter is FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.

Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero.

Remarks
If the bRepaint parameter is TRUE, Windows sends the WM_PAINT message to the window procedure immediately after moving the window (that is, the MoveWindow function calls the UpdateWindow function). If bRepaint is FALSE, Windows places the WM_PAINT message in the message queue associated with the window. The message loop dispatches the WM_PAINT message only after dispatching all other messages in the queue.

VFW: 設定視訊畫面顯示速率

在Preview 顯示模式下, VFW SKD 提供 capPreviewRate 函數來設定視訊畫面的顯示速率。

The capPreviewRate macro sets the frame display rate in preview mode.

BOOL capPreviewRate(
　hwnd,
　wMS
　);

Parameters
hwnd Handle of a capture window.
wMS Rate, in milliseconds, at which new frames are captured and displayed.

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

Remarks
The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. During streaming video capture, the previewing task is lower priority than writing frames to disk, and preview frames are displayed only if no other buffers are available for writing.

注意: 這邊的 wMS 指的就是一個畫面 ( frame ) 要顯示多少毫秒 ( msec ), 單位是 msec/frame, 若要轉換成我們一般習慣的每秒顯示多少個畫面, 單位是 frame/sec, 則是 1sec. = 1000 msec. 例如: 每個畫面顯示 20 毫秒, 代表每秒種可以顯示 1000/20 = 50 個畫面。
　

VFW: 設定顯示模式

視訊顯示模式分成兩種:
一、Preview 顯示模式:
從視訊裝置取得的影像資料會先放在系統記憶體中, 然後再顯示於螢幕上。這些處理過程全都要仰賴 CPU 處理, 因此效率較差。在 Preview 模式下, 可以透過 capPreviewRate 函數設定視訊畫面的顯示速率與透過 capPreviewScale 調整顯示畫面尺寸。VFW SDK 提供了 capPreview 函數來啟動 Preview 顯示模式。

The capPreview macro enables or disables preview mode. In preview mode, frames are transferred from the capture hardware to system memory and then displayed in the capture window using GDI functions.

BOOL capPreview(
　hwnd,
　f
　);

Parameters
hwnd Handle of a capture window.
f Preview flag. Specify TRUE for this parameter to enable preview mode or FALSE to disable it.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
The preview mode uses substantial CPU resources. Applications can disable preview or lower the preview rate when another application has the focus. The fLiveWindow member of the CAPSTATUS structure indicates if preview mode is currently enabled. Enabling preview mode automatically disables overlay mode.

二、Overlay 顯示模式:
視訊裝置會直接將影像資料覆疊到螢幕上, 因此, 並不會佔用系統的 CPU 與記憶體資源, 所以顯示效率較好。不過, 並不是所有的視訊裝置都支援 Overlay 模式, 像 USB 攝影機就不支援 Overlay 顯示模式。 VFW SDK 提供 capOverlay 函數來啟動 Overlay 顯示模式。

The capOverlay macro enables or disables overlay mode. In overlay mode, video is displayed using hardware overlay.

BOOL capOverlay(
　hwnd,
　f
　);

Parameters
hwnd Handle of a capture window.
f Overlay flag. Specify TRUE for this parameter to enable overlay mode or FALSE to disable it.

Return Values
Returns TRUE if successful or FALSE otherwise.

Remarks
Using an overlay does not require CPU resources. The fHasOverlay member of the CAPDRIVERCAPS structure indicates whether the device is capable of overlay. The fOverlayWindow member of the CAPSTATUS structure indicates whether overlay mode is currently enabled. Enabling overlay mode automatically disables preview mode.

註: USB 攝影機將類比影像訊號轉成數位資料, 透過 USB 傳輸介面傳送到系統記憶體中, 然後 CPU 再將影像資料顯示於螢幕上。至於影像擷取卡, 透過 A/D 轉換模組, 將類比影像訊號轉成數位資料, 並儲存於影像擷取卡的記憶體中。某些較高階的影像擷取卡還包含了影像處理晶片, 提供一些基本的影像處理功能。
　

VFW: 取得視訊裝置驅動程式的效能

由於各家視訊裝置所提供的驅動程式功能並不完全相同, 因此, 我們開發的應用程式有必要了解自己所安裝的驅動程式到底提供了什麼功能。VFW SDK 提供了 capDriverGetCaps 函數來讓你了解自己的視訊系統。

The capDriverGetCaps macro returns the hardware capabilities of the capture driver currently connected to a capture window.

capDriverGetCaps(
　hwnd,
　psCaps,
　wSize
　);

Parameters
hwnd Handle of a capture window.
psCaps Address of the CAPDRIVERCAPS structure to contain the hardware capabilities.
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 capabilities returned in CAPDRIVERCAPS are constant for a given capture driver. Applications need to retrieve this information once when the capture driver is first connected to a capture window.

呼叫了這個函數後, 我們的應用程式就會得知你的電腦中代表該視訊驅動程式的索引值, 你的視訊裝置有沒有提供影像 Overlay 模式, 提供了哪些對話盒供你呼叫使用...等等。

既然這個函數要告訴我們這麼多資料, 顯然呼叫時, 就要設定很多個輸入或輸出的參數。為了方便我們使用, VFW 所採用的作法就是在 vfw.h, line 3493 起, 宣告了 tagCapDriverCaps 結構資料型態攻供我們使用:

typedef struct tagCapDriverCaps {
　UINT wDeviceIndex; // Driver index in system.ini
　BOOL fHasOverlay; // Can device overlay?
　BOOL fHasDlgVideoSource; // Has Video source dlg?
　BOOL fHasDlgVideoFormat; // Has Format dlg?
　BOOL fHasDlgVideoDisplay; // Has External out dlg?
　BOOL fCaptureInitialized; // Driver ready to capture?
　BOOL fDriverSuppliesPalettes; // Can driver make palettes?
　// following always NULL on Win32.
　HANDLE hVideoIn; // Driver In channel
　HANDLE hVideoOut; // Driver Out channel
　HANDLE hVideoExtIn; // Driver Ext In channel
　HANDLE hVideoExtOut; // Driver Ext Out channel
　} CAPDRIVERCAPS, *PCAPDRIVERCAPS, FAR *LPCAPDRIVERCAPS;

因此, 我們只要在程式中宣告一個變數 s 屬於 tagCapDriverCaps 資料型態, 我們就可以將 s 的位址 &s 放到 capDriverGetCaps 的參數之中來用了。

範例程式:
// 宣告部份:
tagCapDriverCaps s;

// 呼叫與傳回值使用部份
if (capDriverGetCaps(hwndVideo,&s,sizeof(s)))
　{
　if ( s.fHasOverlay )
　　lblOverlay->Caption = AnsiString("Overlay: Yes");
　else
　　lblOverlay->Caption = AnsiString("Overlay: No");
　}
　

VFW: 連結視訊擷取視窗與視訊裝置

The capDriverConnect macro connects a capture window to a capture driver.

BOOL capDriverConnect(
　hwnd,
　iIndex
　);

Parameters
hwnd Handle of a capture window.
iIndex Index of the capture driver. The index can range from 0 through 9.

Return Values
Returns TRUE if successful or FALSE if the specified capture driver cannot be connected to the capture window.

Remarks
Connecting a capture driver to a capture window automatically disconnects any previously connected capture driver.

當我們的應用程式建立一個視訊擷取視窗時, 視窗的畫面仍然會黑壓壓的一片, 這是由於視訊裝置所拍攝的資料並沒有餵進所建立之視訊擷取視窗的緣故。我們可以用 capDriverConnect 這個函數將兩者連結起來。很自然而然地, 輸入參數一個是之前建立視窗時傳回的 handle 值, 另一個是視訊裝置驅動程式的編號 iIndex。不過, 要中斷兩者的連結 capDriverDisconnect , 只要指出哪個視訊擷取視窗要中斷連結即可, 並不需要指出兩邊的參數。

The capDriverDisconnect macro disconnects a capture driver from a capture window.

BOOL capDriverDisconnect(
　hwnd
　);

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

注意: 連結成功後, 視訊擷取視窗的影像仍然是靜態的, 並不是即時動態的視訊資料, 這是由於尚未 設定顯示模式 的緣故。
　

VFW: 如何建立一個視訊擷取視窗

The capCreateCaptureWindow function creates a capture window.

HWND VFWAPI capCreateCaptureWindow(
LPCSTR lpszWindowName,
DWORD dwStyle,
int x,
int y,
int nWidth,
int nHeight,
HWND hWnd,
int nID
);

Parameters
lpszWindowName Null-terminated string containing the name used for the capture window.
dwStyle Window styles used for the capture window.
( Note: Window styles are described with the CreateWindowEx function.)
x and y The x- and y-coordinates of the upper left corner of the capture window.
nWidth and nHeight Width and height of the capture window.
hWnd Handle of the parent window.
nID Window identifier.

Return Values
Returns a handle of the capture window if successful or NULL otherwise.

看完 BCB Help 的說明後, 我們一樣也來看看 vfw.h 之中, capCreateCaptureWindow 是如何宣告的:

HWND VFWAPI capCreateCaptureWindowA (
LPCSTR lpszWindowName,
DWORD dwStyle,
int x, int y, int nWidth, int nHeight,
HWND hwndParent, int nID);

HWND VFWAPI capCreateCaptureWindowW (
LPCWSTR lpszWindowName,
DWORD dwStyle,
int x, int y, int nWidth, int nHeight,
HWND hwndParent, int nID);

我們要建立一個視訊擷取視窗, 自然要告訴電腦要把視窗建立在哪邊? 是要直接放在 Form 上呢? 還是放在 Form 上的 Panel 物件上呢? 因此, 我們必須透過 handleParent 這個參數來告訴電腦, 也就是需要告訴電腦一個代碼, 這個代碼表示了所產生的視窗將要顯示在哪個物件之上。除此, 要放在這個物件的何處, 則是透過 x, y 來指定視窗的左上角要放這個物件的哪一個 ( x, y ) 座標上; 至於所建立的擷取視窗大小則是透過 nWidth 與 nHeight 兩個參數來表示。

capCreateCaptureWindow 的傳回值的資料型態為 HWND, 也就是所建立的視訊擷取視窗的代碼 ( handle ), 將來我們程式中要提到或針對此視窗的相關處理時, 只要指明這個代碼即可。

要關閉視訊擷取視窗的方法, 如同要關閉一般視窗一樣, 只要利用 Win32 API 的 DestroyWindow 函數, 並告訴電腦你要關閉的視窗代碼 ( handle ) 即可。

程式範例:
HWND hwndVideo;

hwndVideo = capCreateCaptureWindow(
(LPSTR) "My Capture Window", WS_CHILD | WS_VISIBLE,
0, 0, iImageWidth, iImageHeight, Form1->pnlCapture1->Handle, 1 );

VFW: 取得視訊裝置驅動程式的資訊

任何一個電腦週邊硬體裝置安裝時, 作業系統必須要能與硬體裝置溝通, 我們把溝通媒介稱為驅動程式 ( device driver )。電腦與周邊裝置的溝通必需透過特定介面傳送資料, 傳送的資料也必須符合特定格式, 驅動程式可以認得傳送的資料為何, 就可以驅動硬體裝置執行電腦所派達的命令。

我們可以透過 capGetDriverDescription 這個函數, 讓應用程式知道你所使用的視訊裝置驅動程式相關資訊。如果你在 vfw.h 中搜尋, 你可以在 line 3618 找到底下這段定義與函數的宣告。

BOOL VFWAPI capGetDriverDescriptionA (UINT wDriverIndex,
LPSTR lpszName, int cbName,
LPSTR lpszVer, int cbVer);

BOOL VFWAPI capGetDriverDescriptionW (UINT wDriverIndex,
LPWSTR lpszName, int cbName,
LPWSTR lpszVer, int cbVer);

#ifdef UNICODE
#define capCreateCaptureWindow capCreateCaptureWindowW
#define capGetDriverDescription capGetDriverDescriptionW
#else
#define capCreateCaptureWindow capCreateCaptureWindowA
#define capGetDriverDescription capGetDriverDescriptionA
#endif

/* 說明:
1. 有關 #ifdef 的 C 前置處理的部份, 請參考 http://nknucc.nknu.edu.tw/~jwu/c/cpgch8.htm
2. capGetDriverDescriptionA 函數的傳回值為 BOOL ( 布林值, true or false ) , 傳入值一共有 5 個分別如下:
UINT wDriverIndex, 指定要取得的視訊裝置編號。( 你要先告訴人家要取得哪一個視訊裝置的相關資訊! )
LPSTR lpszName, 取得驅動程式的名稱後, 要儲存到哪一個字串給你知道呢?
( 注意: 這邊傳入的是這個字串的指標! )
int cbName, 指定存放驅動程式名稱的字串的大小。
LPSTR lpszVer, 取得驅動程式的版本後, 存放在這個字串中。
int cbVer, 指定存放驅動程式版本的字串的大小。
*/

範例程式:
long dwDriverIndex;
char szDeviceName[80]; // Driver Name
char szDeviceVersion[80]; // Driver Version

dwDriverIndex = 0;
if (capGetDriverDescription(dwDriverIndex, szDeviceName, sizeof(szDeviceName),
szDeviceVersion, sizeof(szDeviceVersion)))
{
lblCapDriverName->Caption = szDeviceName;
lblCapDriverVer->Caption = szDeviceVersion;
}