第三章 遊戲開發類別庫說明
3.4 GAF函數說明
在下一章的遊戲實作說明之前，我必須先簡單地介紹一下幾個GAF 的主要類別及其函數之功能。
3.4.1 GAFApp類別
這個類別主要是跟視窗建立、訊息機制有關。
1. 函數：virtual BOOL InitInstance();
功能：初始化視窗實體，可以由使用者重新載入初始化自己的資料。
2. 函數：virtual int ExitInstance();
功能：結束視窗實體，可以由使用者重新載入釋放自己的資料。
3. 函數：virtual int Run();
功能：遊戲主循環迴圈，可以由使用者重新載入做自己的遊戲循環。
4. 函數：virtual void OnIdle();
功能：訊息空閒時間處理，可以在這裡放置重繪和更新遊戲資料操 作。
5. 函數：BOOL HandleMessage();
功能：阻塞訊息循環，如果沒有訊息則呼叫OnIdle()。返回FALSE 則表示可以退出程式。
6. 函數：BOOL ProcessMessage();
功能：異步消息處理，由程式設計者自己控制消息處理，不呼叫 OnIdle()，返回FALSE則表示可以退出程式。
7. 函數：void BindWndMenu(UINT uID);
功能：給視窗新增功能表。參數uID是功能表的資源ID編號。
8. 函數：void BindWndClassName(LPCTSTR szWndClassName=GAFDEFWNDCLASSNAME);
void BindWndClassName(UINT uID);
功能：修改視窗類別。這個函數有兩個形式，第一個形式可以通過 指定字串來修改視窗類別名稱，第二個形式則通過資源ID編號。
9. 函數：void BindWndTitle(LPCTSTR szWndTitle=GAFDEFWNDTITLE);
void BindWndTitle(UINT uID);
功能：修改視窗標題。這個函數有兩個形式，第一個形式通過字串 來修改視窗標題，第二個形式則通過資源ID編號。
10. 函數：void BindWndWidth(int w);
功能：修改視窗寬度。參數w是你想要的視窗寬度。
11. 函數：void BindWndHeight(int h);
功能：修改視窗高度。參數h是你想要的視窗高度。
12. 函數：void BindWndIcon(UINT uID);
功能：修改視窗小圖示。參數uID是小圖示的資源ID編號。
13. 函數：void BindWndStyle(DWORD dwExStyle=WSEXAPPWINDOW, DWORD dwStyle=WSPOPUP|WSVISIBLE|WSCAPTION|WSSYSMENU);
功能：修改視窗風格。第一個參數dwExStyle指定視窗延伸風格，
第二個參數dwStyle指定視窗基本風格。通常情況下可以選擇預設 值，即不填寫任何參數。
14. 函數：void ScreenToClient(LONG *px, LONG *py);
void ScreenToClient(LPPOINT lpPoint);
功能：將螢幕座標轉換為客戶區(即除了標題，視窗邊框以及功能 表工具欄區的視窗範圍)座標。有兩種形式，第一個可以指定要轉 換的座標x和y座標值，第二種可以指定一個POINT指標。
15. 函數：void ClientToScreen(LONG *px, LONG *py);
void ClientToScreen(LPPOINT lpPoint);
功能：將客戶區座標換成螢幕座標。有兩種形式，第一種可以指定 要轉換的座標的x和y座標值，第二種可以指定一個POINT指標。
16. 函數：virtual int OnActivateApp(BOOL bActive, DWORD dwThreadID);
virtual int OnCreate(LPCREATESTRUCT lpCreateStruct);
virtual int OnSetFocus();
virtual int OnChar(UINT nChar, UINT nRepCnt, UINT nFlags);
virtual int OnClose(HWND hWnd);
virtual int OnCommand(UINT nNotifyCode, UINT uID, HWND hWndCtrl);
virtual int OnDestroy();
virtual int OnKeyDown(UINT nChar, UINT nRepCnt, UINT nFlags);
virtual int OnKeyUp(UINT nChar, UINT nRepCnt, UINT nFlags);
virtual int OnKillFocus();
virtual int OnLButtonDblClk(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnLButtonDown(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnLButtonUp(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnMouseMove(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnRButtonDblClk(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnRButtonDown(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnRButtonUp(UINT nFlags, LONG XPos, LONG YPos);
virtual int OnPaint(HDC hDC);
virtual int OnSetCursor(HWND hWnd, UINT nHitTest, UINT message);
virtual int OnShowWindow(BOOL bShow, UINT nStatus);
virtual int OnTimer(UINT nIDEvent, TIMERPROC *tmPrc);
功能：由於訊息處理函數比較多，所以下面做統一的介紹。這裡所 有的參數均不需要填寫，由Windows訊息機制來完成。
OnActivateApp函數處理程式被啟動或由活動狀態轉為非活動狀態 的訊息。bactive表示視窗是否被啟動，dwThreadID是執行緒ID編 號。
OnCreate函數處理視窗建立訊息。
OnSetFocus函數處理視窗獲得焦點訊息。
OnChar函數處理鍵盤訊息、nChar是虛擬鍵盤值。
OnClose函數處理視窗關閉訊息、hWnd是視窗控制碼。
OnCommand函數處理功能表、控制項訊息。
OnDestroy函數處理視窗銷毀訊息。
OnKeyDown函數處理鍵盤按鍵按下的訊息。
OnKeyUp函數處理鍵盤按鍵放開的訊息。
OnKillFocus函數處理視窗失去焦點的訊息。
OnLButtonDblClk函數處理滑鼠左鍵雙擊訊息，XPos和YPos分別代 表滑鼠所處的座標的x和y座標。相應的函數有：
OnLButtonDown, OnLButtonUp, OnRButtonDblClk, OnRButtonDown, OnRButtonUp。它們分別處滑鼠左鍵按下、放開，滑鼠右鍵雙擊、
按下、放開的訊息。
OnMouseMove函數處理滑鼠移動訊息。XPos和YPos分別代表滑鼠所 處位置。
OnPaint函數處理視窗重繪訊息。
OnSetCursor函數處理螢幕上的滑鼠設置訊息。
OnShowWindow函數處理視窗顯示訊息。bShow代表視窗是否被顯示。
OnTimer函數處理計時器訊息。
3.4.2 GAFDDraw類別
這個類別如同之前所說的，是對應於DirectX的DirectDraw，主要 是用來設定圖片，不論是背景或是圖片表層，都可以在此設定顯示模 式，另一個重點則是顯示放記憶體的使用與釋放。
1. 函數：HRESULT CreateFullScreen(HWND hWnd, DWORD Width, DWORD Height);
功能：設置寬高為指定值的全螢幕16bit模式，並且自動建立主表 面和後臺表面的翻轉鏈。hWnd指定視窗的控制碼，Width指定表面 寬度，Height指定表面高度。
2. 函數：HRESULT CreateWindowMode(HWND hWnd, DWORD Width, DWORD Height, BYTE bBackSurfacePos=GAFMEMVIDTHENSYS);
功能：設置寬高為指定值的視窗模式，如果視窗客戶區小於指定大
3. 函數：HRESULT Present(BOOL Vsync=TRUE, BOOL displayFPS=FALSE);
功能：用來顯示表面，如果是全螢幕模式則自動翻轉主後表面，如 果是視窗模式會自動Blt，預設值為TRUE。VSync指定是否等待顯示 器垂直回掃週期。displayFPS指定是否顯示每秒幀速率，預設為 FALSE。
4. 函數：HRESULT Restore();
功能：發生主表面資料遺失的時候，自動恢復主表面。這個操作會 由GAFDDraw自動呼叫自動完成。
5. 函數：BOOL is555();
功能：檢查顯示卡的16位元顏色模式是否是555格式，如果顯示卡 支持555格式的16位色，則返回TRUE。
6. 函數：BOOL isFullScreen();
功能：檢查程式是否為全螢幕模式。如果是全螢幕模式，則返回 TRUE。
7. 函數：LPDIRECTDRAW7 GetDD();
功能：獲取原始的LPDIRECTDRAW7介面。
8. 函數：LPCGAFDDRAWSURFACE GetPrimary();
功能：獲取由GAFDDraw生成的主表面(前臺緩衝)。
9. 函數：LPCGAFDDRAWSURFACE GetBack();
功能：獲取由GAFDDraw生成的後臺緩衝。
3.4.3 GAFDDrawSurface類別
這個類別跟上一個類別有很密切的關係，它的主要用途是設定圖層 的載入、屬性設定等。
1. 函數：HRESULT CreateSurface(LPCGAFDDRAW lpGAFDD, int Width , int Height, BYTE MemoryType=GAFMEMVIDTHENSYS);
功能：建立一個空的指定大小的圖層表面，可以指定表面放的位
2. 函數：HRESULT CreateByJPEG(LPCGAFDDRAW lpGAFDD, LPCTSTR szFileName, BYTE MemoryType=GAFMEMVIDTHENSYS);
功能：根據一個JPEG檔來自動建立表面。lpGAFDD指定GAFDDraw類 別指標。SzFileName指定需要載入的圖檔檔名。MemoryType指定表 面所在位置。用法同上。
3. 函數：HRESULT CreateByBitmap(LPCGAFDDRAW lpGAFDD, LPCTSTR szFileName, BYTE MemoryType-GAFMEMVIDTHENSYS);
功能：根據一個BMP檔來自動建立表面。參數用法同上。
4. 函數：HRESULT Restore();
功能：圖層資料遺失的時候自動呼叫Restore恢復圖層，但是目前 還沒有自動恢復圖層內圖像的功能。
5. 函數：HRESULT BltFastTo(CGAFDDrawSurface *lpDDS, LONG lDestX, LONG lDestY, BOOL bTrans, LPRECT srcRect=NULL, BOOL
bAutoClip=TRUE);
功能：向lpDDS表面複製圖像。lpDDS是目標表面的指標。lDestX 和lDestY分別指定目標位置的x和y座標。bTrans決定是否做透明色 檢查。srcRect指定要複製的矩形區域指標，如為NULL則為複製整 個圖層。bAutoClip指定是需要自動裁剪(比如要複製的區域超出目 標圖層的部分會被自動裁掉)。
6. 函數：HRESULT BltTo(CGAFDDrawSurface *lpDDS, LONG lDestX, LONG lDestY, BOOL bTrans, LPRECT srcRect = NULL, BOOL
bAutoClip = TRUE);
功能：功能和參數用法同上。
7. 函數：HRESULT StretchBltTo(CGAFDDrawSurface *lpDDS, BOOL bTrans, LPRECT destRect = NULL, LPRECT srcRect = NULL, BOOL bAutoClip = TRUE);
功能：功能和參數用法大致同上，但可以指定目標圖層上接受圖像 的區域大小。destRect指定複製到目標表面的矩形區域指標，如果 為NULL則為複製到整個圖層。
8. 函數：HRESULT BltFast(CGTAFDDrawSurface *lpDDS, LONG lDestX, LONG lDestY, BOOL bTrans, LPRECT srcRect=NULL, BOOL
bAutoClip=TRUE);
HRESULTBlt(CGTAFDDrawSurface *lpDDS, LONG lDestX, LONG lDestY, BOOL bTrans, LPRECT srcRect=NULL, BOOL
bAutoClip=TRUE);
HRESULT StretchBlt(CGTAFDDrawSurface *lpDDS, BOOL bTrans, LPRECT destRect=NULL, LPRECT srcRect=NULL , BOOL
bAutoClip=TRUE);
功能：功能與前面介紹的3個函數一樣，不過這裡是將lpDDS表面的 圖像複製過來。
9. 函數：void SetClipRect(const LPRECT lprt=NULL);
功能：設置表面可以接受圖片位元傳送的區域。lprt指定裁剪區矩 形，如果為NULL則指定整個表面。
10. 函數：BOOL ClipRect(LPRECT lprt);
功能：根據表面自身的裁剪區域來裁剪矩形區域。lprt指定該矩形 區域。
11. 函數：BOOL ClipRectOffset(LPRECT lprt, LONG *plDestX, LONG
*plDestY);
功能：根據表面自身的裁剪區域來裁剪位移(lDestX, lDestY)以後 的lprt。
12. 函數：void GetSurfaceRect(LPRECT lprt);
功能：獲取整個表面的區域。lprt為呼叫後獲得的矩形區域的指標。
13. 函數：DWORD GetWidth();
DWORD GetHeight();
功能：獲取表面的寬度和高度。返回值分別為寬度和高度值。
14. 函數：LPDIRECTDRAWSURFACE7 GetSurface();
功能：獲取原始的LPDIRECTDRAWSURFACE7介面。
15. 函數：HRESULT SetColorKey(DWORD dwColorKey);
HRESULT SetColorKey();
功能：設置顏色鍵。第一個函數指定dwColorKey為顏色鍵。第二個 函數則設置圖片左上角的像素為顏色鍵。
16. 函數：HRESULT Lock(LPRECT lprt=NULL);
HRESULT Unlock(LPRECT lprt=NULL);
功能：第一個函數Lock用於鎖定表面。lprt指定要鎖定的區域，如 果為NULL則鎖定整個表面。第二個函數Unlock則是解鎖表面。
17. 函數：DWORD GetPitch();
功能：獲取鎖定以後的每行字節數。
18. 函數：BYTE* GetSurfacePointer();
功能：獲取鎖定以後的記憶體指標。
19. 函數：HRESULT Fill(DWORD FillColor, LPRECT lprt=NULL, BOOL bAutoClip=FALSE);
功能：用指定顏色填充矩形。FillColor指定要填充的顏色鍵。lprt 指定要填充的矩形區域，如果為NULL則填充整個表面。bAutoClip 指定是否要進行自動裁剪，預設為FALSE。
20. 函數：HRESULT SetFont(const LPCTSTR szFontName, const int nHeight, const int nWidth=0, const int
nAttributes=FWNORMAL);
功能：設置字體。SzFontName指定字體名。nHeight指定字體高度。
nWidth指定字體寬度，預設為0。nAttributes指定字體風格，預設 為FWNORMAL。
21. 函數：HRESULT TextXY(int x, int y, DWORD col, LPCTSTR pString);
功能：在表面上顯示文字。x,y指定了文字在表面上的位置的座標。
Col指定文字的顏色。pString指定文字內容。
22. 函數：HDC GetDC();
功能：獲取表面的DC。返回值為DC的控制碼。
23. 函數：HRESULT ReleaseDC();
功能：釋放表面DC。
3.4.4 GAFDInput類別
這個類別主要是對DirectX裡的DirectInput元件進行封裝，並且 額外對立即方式的輸入增加了「按鍵放開」的支援。不過此類別並沒 有提供對搖桿的支援。
1. 函數：HRESULT InitDInput(const HINSTANCE hInstance, const HWND hWnd);
功能：用來初始化DInput，HInstance和HWnd是主程式的視窗實體 和視窗控制碼。
2. 函數：HRESULT Update(BOOL updateMouse=TRUE, BOOL updateKeyboard=TRUE);
功能：更新DInput狀態，獲取新的資料，可以指定是否更新滑鼠或 者鍵盤。
3. 函數：intGetKeyState(int nKeyIndex);
int GetMouseKeyState(int nMouseKeyIndex);
功能：讀取鍵盤按鍵狀態和滑鼠按鍵狀態。KeyIndex為按鈕的索引 號，比如DIK_SPACE，DIK_ESCAPE，DIK_E等等。滑鼠按鈕索引為 DIK_MOUSELEFT，DIK_MOUSERIGHT等。
返回值：
GAFDIKEY_NONE //當前按鍵未按下 GAFDIKEY_RELEASE //按鍵恰好放開 GAFDIKEY_PRESS //按鍵按下
4. 函數：void GetMousePos(LONG *px, LONG *py);
void GetSysMousePos(LONG *px, LONG *py);
功能：獲取DInput滑鼠位置和獲取系統預設滑鼠位置。DInput的滑
5. 函數：void SetMouseAcceleration(BOOL ac);
BOOL IsMouseAcceleartion();
功能：設置和讀取GAFDInput滑鼠自動加速開關。當覺得DInput的 滑鼠速度慢時，那就打開這個選項。
6. 函數：HRESULT SetMouseExculsive(BOOL ExclusiveMouseAccess);
功能：設置是否採用滑鼠獨佔瀏覽。
7. 函數：void SetMouseLimit(LONG x1, LONG y1, LONG x2, LONG y2);
void SetMouseLimit(const LPRECT lprt);
功能：設置滑鼠運動範圍，可以使用左上角(x1,y1)和右下角(x2,y2) 座標來指定範圍，也可以使用RECT來指定一個矩形區域。如果不指 定，那麼GAFDInput將自動指定運動範圍為螢幕範圍。
8. 函數：BOOL hasKeyBoard();
BOOL hasMouse();
功能：查詢是否擁有滑鼠和鍵盤設備的不常用功能。