Direct3D Workshop November 17, 2005 Workshop by Geoff Cagle Presented by Players 2 Professionals

Workshop Breakdown ► Part 1: Graphics Pipeline ► Part 2: Projection Space ► Part 3: Windows Programming ► Intermission ► Part 4: Setting Up Direct3D ► Part 5: Using Direct3D

Notes and Code Samples ► You can download these notes and all the code samples from

Part 3 Windows Programming

code1.cpp ► This part of the workshop is basically a big explanation for code1.cpp which creates a window. ► You may find it helpful to look at code1.cpp as you go through the slides.

What is a “window?” ► The most obvious windows are the application windows on your desktop. ► The term “window” also refers to any child window or control (such as a button) within a window. ► Windows are organized in a hierarchy.

Example - Calculator

Event Driven Programming ► Windows programming is event driven. ► An event driven program sits and waits for an event to process. ► Events include moving or sizing a window, clicking the mouse button over a window, or typing keys on the keyboard. ► Windows programs are notified of events by messages sent from the OS.

Win32 API ► We will use the Win32 Platform API to write a windows program.  Typically more tedious, but we only need to create one window.  Faster and Smaller executable.  Written in C. ► Other options include:  MFC, Qt, wxWindows, SDL,.NET Forms

WinMain ► Instead of main, windows programs use WinMain ► WinMain has different parameters:  HINSTANCE hInstance – a handle to the program  HINSTANCE hPrevInstance – no longer used.  LPSTR lpCmdLine – unparsed command line. Doesn’t include executable’s filename.  int nCmdShow – Specifies how the window should be initially shown (ie. Minimized, Maximized, Normal) ► WinMain must have a WINAPI modifier.  int WINAPI WinMain (…) ► WinMain still returns an integer like main.

Headers ► To use the Win32 API we need to #include windows.h ► If we #define WIN32_LEAN_AND_MEAN before #including windows.h, the compiler will skip compiling the more rarely used windows code.

Windows Program Outline ► Create Window Class ► Create Window ► Show the Window ► Enter Message Loop

Window Classes ► A window class acts as a template for window creation. ► Window classes are not classes in the C++ sense. ► We can set such properties as:  Name of the window class – important for identifying it later!  Window style – How it looks and its default behaviors.  Window procedure – a pointer to function that handles messages for a window.  Default cursor, icon, and menu.

Creating a Window Class ► Fill out a WNDCLASS or WNDCLASSEX structure. ► Use the structure to register the class with a call to RegisterClass or RegisterClassEx, respectively.

Create the Window ► Create a Window with a call to CreateWindow or CreateWindowEx. ► Some of the parameters you will need to enter include:  The name of a window class.  The name of the window.  A handle to a parent window. ( NULL if no parent)  Initial size and position of the window. ► CreateWindow and CreateWindowEx will return a window handle ( HWND ) if successful or NULL if failed.

Showing the Window ► When we create a window it starts off hidden. ► To show the window you must call ShowWindow (hWnd, nCmdShow)  hWnd – returned from CreateWindow / Ex.  nCmdShow – parameter from WinMain.  This will send a message to the window telling it to show. ► Call UpdateWindow (hWnd) to force the window to process the show message immediately.

Message Loops ► A message loop is needed to forward messages to their windows. ► There are different ways to make a message loop but here is the most common one: MSG msg = {0}; // returns FALSE when message is WM_QUIT while (GetMessage (&msg, NULL, 0, 0)) { TranslateMessage (&msg); // translate keyboard messages. DispatchMessage (&msg); // send message to its window. }

Message Loop (Cont’d) ► The loop uses:  A MSG structure – Holds message information.  GetMessage – Retrieves the next message. Waits for a message if the message queue is empty.  TranslateMessage – Translate some keyboard messages.  DispatchMessage – Dispatches the message to the appropriate windows procedure.

Windows Procedure ► Every window has an associate procedure for handling messages. ► Windows procedures have the following format:  LRESULT CALLBACK ProcName (HWND hwnd, UINT msg, WPARAM wp, LPARAM lp);

Window Procedure Example ► Here is an example procedure: LRESULT CALLBACK WndProc (HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) { switch (msg) { case WM_DESTROY: PostQuitMessage (0); return 0; } return DefWindowProc (hwnd, msg, wp, lp); }

Window Procedure Parameters ► The procedure has 4 parameters:  HWND hwnd – handle to the window receiving the message. This is useful when multiple windows share the same procedure. You can think of it sort of like a this pointer.  UINT msg – The message.  WPARAM wp and LPARAM lp – These are parameters to the message and may represent different things.

Window Procedure Return ► When the procedure completely handles a message, it should return 0. ► The procedure should let the OS handle all other messages by calling DefWindowProc and then return its result.

WM_DESTROY and WM_QUIT ► For this workshop we only want to handle one message: WM_DESTROY.  This message is called when a window is closed.  Note that just because the window is destroyed, the program will still run.  To end the program we send WM_QUIT by calling PostQuitMessage.

WM_* ► Other messages you may want to handle include:  WM_CREATE  WM_SIZE  WM_LBUTTONDOWN  WM_LBUTTONUP  WM_MOUSEMOVE  WM_KEYDOWN  WM_KEYUP ► Check MSDN literature for information about these messages:

Code1.cpp ► This completes Part 3 of the workshop. ► To see how this all works check out code1.cpp, included with this workshop.

Make sure you select Win32 Project.

Make sure you create an empty project.

Code1.exe in Action

References 1. Programming Windows 5 th Edition by Charles Petzold. The definitive guide to Win32 API Programming. 2. MSDN’s Win32 API Reference: asp?url=/library/en- us/winprog/winprog/windows_api_start_p age.asp asp?url=/library/en- us/winprog/winprog/windows_api_start_p age.asp asp?url=/library/en- us/winprog/winprog/windows_api_start_p age.asp