TRect type

TRect defines a rectangle.

Unit
Types

struct TRect
　{
　TRect() {}
　TRect(const TPoint& TL, const TPoint& BR)
　　{ left=TL.x; top=TL.y; right=BR.x; bottom=BR.y; }
　TRect(int l, int t, int r, int b)
　　{ left=l; top=t; right=r; bottom=b; }
　TRect(RECT& r)
　　{
　　left = r.left;
　　top = r.top;
　　right = r.right;
　　bottom = r.bottom;
　　}

int Width() const { return right - left; }
int Height() const { return bottom - top ; }
bool operator ==(const TRect& rc) const
　{
　return left == rc.left && top==rc.top &&
　right == rc.right && bottom==rc.bottom;
　}
bool operator !=(const TRect& rc) const
　{ return !(rc==*this); }
　__property LONG Left = { read=left, write=left };
　__property LONG Top = { read=top, write=top };
　__property LONG Right = { read=right, write=right };
　__property LONG Bottom = { read=bottom, write=bottom };
　};

Description
TRect represents the dimensions of a rectangle. The coordinates are specified as either four separate integers representing the left, top, right, and bottom sides, or as two points representing the locations of the top left and bottom right corners.

Typically, TRect values represent pixel locations, where the origin of the pixel coordinate system is in the top left corner of the screen (screen coordinates) or the top left corner of a control client area (client coordinates). When a TRect value represents a rectangle on the screen, by convention the top and left edges are considered inside the rectangle and the bottom and right edges are considered outside the rectangle. This convention allows the width of the rectangle to be Right - Left and the height to be Bottom - Top.

要特別注意的一點是 TRect 這個長方塊中所指明的區域並不包含 the bottom and right edges, 這是為了讓 rectangle 的長寬值剛好符合座標相減的緣故。
　

TCanvas::CopyRect method

Copies part of an image from another canvas into the canvas.

void __fastcall CopyRect(const TRect &Dest, TCanvas* Canvas, const TRect &Source);

Description
Use CopyRect to transfer part of the image on another canvas to the image of the TCanvas object. Dest specifies the rectangle on the canvas where the source image will be copied. The Canvas parameter specifies the canvas with the source image. Source specifies a rectangle bounding the portion of the source canvas that will be copied.

The portion of the source canvas is copied using the mode specified by CopyMode.

TCanvas::CopyRect method 可以將另外一個 Canvas ( 第二個輸入參數 ) 中的特定長方塊 (rectangle) ( 第三個輸入參數 ) 中的影像 copy 到自己這個 Canvas 的特定長方塊( 第一個輸入參數 ) 中。
　

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 );

RGB macro

The RGB macro selects a red, green, blue (RGB) color based on the arguments supplied and the color capabilities of the output device.

COLORREF RGB(
BYTE bRed, // red component of color
BYTE bGreen, // green component of color
BYTE bBlue // blue component of color
);

Parameters
cRed Specifies the intensity of the red color.
cGreen Specifies the intensity of the green color.
cBlue Specifies the intensity of the blue color.

Return Values
The return value is the resultant RGB color.

Remarks
The intensity for each argument is in the range 0 through 255. If all three intensities are zero, the result is black. If all three intensities are 255, the result is white.

The RGB macro is defined as follows:

#define RGB(r, g ,b) ((DWORD) (((BYTE) (r) | \
((WORD) (g) << 8)) | (((DWORD) (BYTE) (b)) << 16)))

TCanvas

TCanvas 這個類別是用來處理 Window 繪圖的介面, 負責與 Window 的裝置驅動程式溝通, 透過裝置驅動程式將資料顯示在顯示器上面。

C++ Builder 中, 具有 Canvas 的元件有 TForm, TImage, TbitButton ... 等等, 換句話說, 你可以在這些元件上繪圖。

TCanvas 透過畫筆 (TPen) 和 畫刷 (TBrush) 兩個類別來進行繪圖。除此, 也可以直接透過 Pixels property 對畫布上的像素色彩值進行存取。

TCanvas provides an abstract drawing space for objects that must render their own images.

Hierarchy
TObject -> TPersistent -> TCanvas

Unit
Graphics

Description
Use TCanvas as a drawing surface for objects that draw an image of themselves. Standard window controls such as edit controls or list boxes do not require a canvas, as they are drawn by the system.

TCanvas provides properties, events and methods that assist in creating an image by
。Specifying the type of brush, pen and font to use.
。Drawing and filling a variety of shapes and lines.
。Writing text.
。Rendering graphic images.
。Enabling a response to changes in the current image.

TCanvas has two descendants, TControlCanvas and TMetafileCanvas, which assist in drawing images of controls and in creating metafile images for objects.

TColor type

TColor is used to specify the color of an object.

Unit
Graphics

enum TColor {clMin=-0x7fffffff-1, clMax=0x7fffffff};

Description
TColor is used to specify the color of an object. It is used by the Color property of many components and by a number of other properties that specify color values.

The Graphics unit contains definitions of useful constants for TColor. These constants map either directly to the closest matching color in the system palette (for example, clBlue maps to blue) or to the corresponding system screen element color defined in the Color section of the Windows Control panel (for example, clBtnFace maps to the system color for button faces).

If you specify TColor as a specific 4-byte hexadecimal number instead of using the constants defined in the Graphics unit, the low three bytes represent RGB color intensities for blue, green, and red, respectively. The value 0x00FF0000 represents full-intensity, pure blue, 0x0000FF00 is pure green, and 0x000000FF is pure red. 0x00000000 is black and 0x00FFFFFF is white.

If the highest-order byte is zero (0x00), the color obtained is the closest matching color in the system palette. If the highest-order byte is one (0x01), the color obtained is the closest matching color in the currently realized palette. If the highest-order byte is two (0x02), the value is matched with the nearest color in the logical palette of the current device context.

注意: TColor 本身已經是一個最底層的資料型態了, 本身是一個 enum 的型態, 長度為 4 個位元組(bytes) 的整數。

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;
}

VFW.H

Video For Windows ( VFW ) 是 Microsoft 於 1992 年所推出, 針對多媒體視訊的應用程式開發介面 ( Application Programming Interface , API )。只要本身有支援 VFW 的硬體裝置, 都可以透過 VFW SDK ( Software Development Kit ) 來控制, 並開發出有關音訊、視訊的多媒體處理軟體。

在 BCB 的目錄( C:\Program Files\Borland\CBuilder6\ ) 中, 你可以在 Include 子目錄裏找到 vfw.h 這個 header file, 當我們在 BCB 中要使用 VFW SDK 所提供的函數時, 就要將下面一行指令加入到程式的最前面。

#include <vfw.h>
　

Objects

An object is a specific region of memory that can hold a fixed or variable value (or set of values). (This use of the word object is different from the more general term used in object-oriented languages.) Each value has an associated name and type (also known as a data type). The name is used to access the object. This name can be a simple identifier, or it can be a complex expression that uniquely references the object. The type is used

• to determine the correct memory allocation required initially.

• to interpret the bit patterns found in the object during subsequent accesses.

• in many type-checking situations, to ensure that illegal assignments are trapped.

C++Builder supports many standard (predefined) and user-defined data types, including signed and unsigned integers in various sizes, floating-point numbers in various precisions, structures, unions, arrays, and classes. In addition, pointers to most of these objects can be established and manipulated in memory.

The C++Builder standard libraries and your own program and header files must provide unambiguous identifiers (or expressions derived from them) and types so that C++Builder can consistently access, interpret, and (possibly) change the bit patterns in memory corresponding to each active object in your program.

Objects and declarations

Declarations establish the necessary mapping between identifiers and objects. Each declaration associates an identifier with a data type. Most declarations, known as defining declarations, also establish the creation (where and when) of the object; that is, the allocation of physical memory and its possible initialization. Other declarations, known as referencing declarations, simply make their identifiers and types known to the compiler. There can be many referencing declarations for the same identifier, especially in a multifile program, but only one defining declaration for that identifier is allowed.

Generally speaking, an identifier cannot be legally used in a program before its declaration point in the source code. Legal exceptions to this rule (known as forward references) are labels, calls to undeclared functions, and class, struct, or union tags.

TPicture

TPicture contains a bitmap, icon, metafile graphic, or user-defined graphic.

Hierarchy
TObject - TPersistent - TInterfacedPersistent - TPicture

Unit
Graphics

Description
TPicture is a TGraphic container, used to hold a graphic, the type of which is specified in the Graphic property. It is used in place of a TGraphic if the graphic can be of any TGraphic class. LoadFromFile and SaveToFile are polymorphic. For example, if the TPicture is holding an Icon, it is valid to LoadFromFile a bitmap file, where the class TIcon can only read .ICO files.

If the TPicture contains a bitmap graphic, the Bitmap property specifies the graphic. If the TPicture contains an icon graphic, the Icon property specifies the graphic. If the TPicture contains a metafile graphic, the Metafile property specifies the graphic.

The properties of TPicture indicate the type of graphic that the picture object contains, and its size. The methods of TPicture are used to load, save, and manipulate graphics.

To load or save a picture to the Clipboard, use the Assign method of a TClipboard object.

To draw a picture on a canvas, call the Draw or StretchDraw methods of a TCanvas object, passing the Graphic property of a TPicture as a parameter.

TImage

TImage displays a graphical image.

Hierarchy
TObject - TPersistent - TComponent - TControl - TGraphicControl - TImage

Unit
ExtCtrls

Description
Use TImage to display a graphical image on a form. Use the TPicture object in the Picture property to specify the actual bitmap, icon, metafile, or other graphic object displayed by TImage. Properties and methods of TPicture can be used for such things as loading an image from file, clearing the image in the TImage, and assigning an image for another control. TImage introduces several properties to determine how the image is displayed within the boundaries of the TImage object.

To add an image to a form or data module so that it is available for display by other controls, such as action lists and bitmap buttons, use a TImageList control instead.

如果要在 form 中顯示一張影像, 就必須要用到 Image 元件, 可以從 TImage 類別的 Help 資料著手, 了解 BCB 對於顯示影像是如何運作的。在 Image 元件中, 有一個屬性 ( property ) 稱為 Picture, 其型態原型為 TPicture, 是用來儲存影像資料的地方。

Component Palette

BCB 的核心除了以 C++ 程式語言為基礎之外, 最重要的就是 Visual Component Library 了。BCB 把在視窗應用程式 ( window application ) 中常用的一些功能, 包裝成一個個的元件 ( component ), 這些元件通通被放到上圖的 Component Palette 中, 由於元件太多了, 因此 BCB 用分頁選單的方式, 將性質相近的元件放到同一個標籤頁中, 方便我們使用。

你可以比較出畫家用的調色盤 ( palette ) 和 BCB 中的 component palette 之間的異同嗎?

Visual Component Library (VCL)

視覺化元件程式庫( Visual Component Library, VCL ) 是 Borland 所發展出來的, 包含 Objects, Components, Routines, Types, Constants and Variables 等五大部分。底下的說明是從 Borland C++ Builder Help 所寫的說明文字。

Objects
An object consists of methods, and in many cases, properties, and events. Properties represent the data contained in the object. Methods are the actions the object can perform. Events are conditions the object can react to. All objects descend from the ancestor object TObject.

Components
Components are visual objects that you can manipulate at design time. All components descend from TComponent.

Routines
Global routines are the procedures and functions from the runtime library and from the VCL. These routines are not part of a class, but can be called either directly or from within class methods.

Types
The types described in the Help are used as return types and parameter types for object methods, properties and events, and for global routines. In many cases, types are documented in the entry for the method, property, event or global routine in which they are used.

Constants and Variables
The constants and variables defined in the Help are declared in the runtime library and in the VCL. Some of these are instantiations of objects. Examples are the Application and Screen variables. Others represent routines that provide the underlying implementation of other methods or global routines. Examples include the AnsiResemblesProc and RegisterComponentsProc variables. Still other variables and constants represent information that can vary with the system or platform, such as the DateSeparator variable and PathDelim constant.

Borland C++ Builder 是 Borland 針對 C++ 程式語言所開發的快速應用程式開發工具 ( Rapid Application Development, RAD ), Borland 為 C++ 加入了許多的視覺化元件, 配合整合開發環境 ( Integrated Development Environment, IDE ), 推出了 Borland C++ Builder 這個產品, 加速了一個視窗應用程式的開發。

動態宣告二維陣列

寫程式時, 『變數宣告』指的是請作業系統分配 (allocate) 一塊大小合適的記憶體, 讓我們作為儲存資料之用。因此, 我們必須告訴作業系統, 我們要儲存的資料是什麼型態, 然後, 根據程式設計師所提供的變數型態, 作業系統就會知道該分配多大的記憶體給我們使用。因此, 變數宣告通常會寫在程式的最前面, 希望程式一開始執行時, 就把需要用到的記憶體通通分配好。

標題中『動態宣告』指的是當程式設計師在寫程式時, 並無法確實知道程式在執行時需要用的多大的記憶體, 必須等到程式真正執行時(run time), 才會知道確實的大小。為了解決這樣的問題, 就必須允許程式設計師在執行程式時, 才臨時去宣告, 要求分配記憶體, 這就是『動態』兩個字的意義由來。

用二維陣列來儲存數位影像是非常直覺的想法, 不過, 需要用動態宣告方式的原因則是因為我們不知道要事先宣告一個多大的二維陣列才夠儲存你所開啟的影像。這邊就是要介紹 BCB 中, 要動態宣告一個二維陣列的作法。

#include <iostream.h>
// 注意: 必須加入這一行到程式最前面, 否則我們後面用到的 std::bad_alloc 會沒有定義

unsigned char **ucMatrix;
/* 說明:
1. ucMatrix 就是我們要宣告的二維陣列的名稱, 為了讓我們在寫程式時, 一看到這個名稱就知道其資料型態為何, 我們在名稱之前加入了小寫的 uc, 代表 unsigned char 的縮寫,
2. 這邊用 unsigned char 當例子的原因是影像的色彩值範圍為 0 ~ 255, 剛好就是 unsigned char 可以表示的數值範圍。
3. 名稱之前, 我們放了兩個 star 符號 ( ** ), 就是要告訴 BCB 的編譯器, 這個名稱本身是一個指到二維陣列的名稱。
結束說明 */

int iImageHeight=0, iImageWidth=0;
// 說明: 這兩個變數是用來儲存影像 ( image ) 的高 ( height ) 與寬 ( width ) 的, 至於變數名稱最前面的小寫 i, 也是用來指出其資料型態為 int

　try
　　{
　　ucMatrix = new unsigned char *[iImageHeight];
　　for (j=0;j<iImageHeight;j++)
　　　ucMatrix[j] = new unsigned char [iImageWidth];
　　}
　catch (std::bad_alloc)
　　{
　　ShowMessage("Could not allocate memory...Bye");
　　exit(-1);
　　}
　
/* 說明:
1. 如果有一段程式 ( 用大括號 {}, 括起來) 有可能發生一些特殊例外的情況, 以上面的例子來說, 要求系統給予一塊記憶體, 在一般情況下, 這段程式可以順利要到記憶體繼續執行; 可是, 當系統已經沒有多餘的記憶體分配給你的時候, 程式該怎麼辦呢? 這種情況就是可能發生的例外情況。在 C++ (BCB) 中, 你可以將這段程式碼的前面加上 try 這個 keyword, 讓系統知道可能會發生例外情況, 需要例外處理程序支援。
2. 至於不同的例外情況, 要做不同的例外處理, 我們必須用 catch 這個 keyword 來加以分別。以我們的例子來說, 當發生了 std::bad_alloc 這種情況時, 請秀出 "Could not allocate memory... Bye" 字串, 然後程式結束 exit(-1);
3. new 就是提供動態記憶體配置 (dynamic storage allocation) 的指令。如果成功配置到記憶體, new 這個 operator 就會傳回一個指標 (pointer), 指向所配置到的記憶體位置。如果失敗了, new operator 就會呼叫 new_handler 函數。這個函數內定的處理方式就是指出發生了一個 bad_alloc 的例外情況。然後再由程式設計師透過例外處理指令 catch 來接手該如何處理這個例外情況。
4. 由於我們要宣告的是一個二維陣列, 因此整個步驟分成兩部份, 首先要求配置 iImageHeight 個一維陣列的指標, 每一個指標都是指向一個資料型態為 unsigned char 的變數。如果成功了, 就將這個陣列的指標存到 ucMatrix 這個變數中。接著, 再利用for 迴圈要求 iImageHeight 個陣列, 每個陣列都有 iImageWidth 個元素 (elements), 每一個元素的資料型態都是 unsigned char。
結束說明 */

注意: 上述程式為了程式的可讀性, 用了全型的空白"　"來控制部落格文章的內縮顯示。因此, 如果你要直接複製上述程式到 C++ Builder 執行, 請務必將全型空白"　"改成半型空白" ", 否則, 編譯時發出現以下的錯誤訊息。:
[C++ Error] Unit1.cpp(40): E2206 Illegal character '　' (0xa140)

開啟 JPEG 影像

BCB Professional 版本並不提供直接開啟 JPEG 影像的功能, 要開啟 JPEG 影像, 要自己寫 JPEG 的 decoder, 這個有點難度, 不然就是直接上網找別人寫的程式, 弄懂後, 想辦法和自己的程式結合起來。不過, 如果是 BCB Enterprise 版本, 要開啟 JPEG 影像就容易多了, 只要在程式最前面宣告的部份, 加入:

#include "jpeg.hpp"

至於其他的步驟, 則都和 開啟 BMP 影像 相同。

如果你想要看看 jpeg.hpp 這個檔案的內容, 你可以在

C:\Program Files\Borland\CBuilder6\Include\Vcl\

這個目錄中找到這個檔案。如果你沒有安裝 BCB Enterprise 版, 你可以按這邊 一賭為快。