

D3DShell documentation, 26/05/98

Current D3DShell version : 1.1.5


**********************
* What is D3DShell ? *
**********************

D3DShell is a single C file (with its header) which provides a safe Windows
environment for your D3D application.
D3DShell allows the user to change various settings including DirectDraw and
D3D devices, FullScreen/Window mode operation, buffering mode and screen 
resolution at run-time.
DirectX 5.0 or above must be installed to use D3DShell.


***************************
* How do I use D3DShell ? *
***************************

The Project
-----------
Using D3DShell is easy. When you build your D3D application, 
only the following files are needed for your project :

D3DShell.c	Set of functions used to control the rendering
D3DShell.h	Header file for D3DShell.c.
D3DDemo.c	Your demo file. (Must includes D3DShell.h)
D3DDemo.h	Your demo header file (if required).
D3DDemo.rc
+any resource 
file (bmp, ico)	Resources files for your application (if required).

Paths set up or explictly included libraries and include files.
DDRAW.h		DirectDraw header file.
D3D.h		D3D header file.
DDRAW.LIB	DirectDraw library.


Demo Code Exported Functions
----------------------------
In order to interact with D3D Shell, your application MUST include six
functions which are prototyped in D3DShell.h. These functions are called
by D3DShell at run-time so they must exist. These functions are :

  - void InitApplication();

  This function will be called only once by the D3D Shell before anything 
  happens, at the very beginning of the D3DShell WinMain() function. 
  This function enables the user to perform any initialisation before 
  the program is actually run.
  Could be used to load meshes and allocate memory for these, loading
  external libraries, etc...

  Within this function the user can call D3DShellSetPreferences(...) to set 
  the application preferences. For details of this function, see later
  in this document.

  - void QuitApplication();

  This function is used in conjunction with InitApplication(). Its purpose
  is to free and close all memory or instances allocated in InitApplication().
  This function is called when the user exits the application.

				***

  - BOOL InitView(LPDIRECTDRAW2 lpDD2, LPDIRECT3D2 lpD3D2, 
		  LPDIRECT3DDEVICE2 lpDev2, LPDIRECT3DVIEWPORT2 lpView2, 
		  DWORD dwWidth, DWORD dwHeight);

  This function is called each time a rendering variable is changed in
  the D3DShell (changing of DirectDraw or D3D device, switching from or 
  to full screen, changing the resolution, changing the buffering mode 
  and switching Display Info On or Off). 
  
  InitView(...) is the final function that gets called when rendering 
  variables are changed.
  InitView(...) lets the user create or initialise any new variables 
  corresponding to the new rendering parameters. 
  In this function you may load textures, set up matrices, create materials,
  lights, set render states, create execute buffers (if required), etc...
  It is very important to perform the above tasks in this function, as the
  D3D or DirectDraw devices can be changed by the user, thus requiring to
  recreate all the new variables according to the new selected devices.
  The variables passed to this function are interfaces to DirectDraw or
  D3D objects. You can use them to call any D3D functions : lpD3D2 to 
  create materials, lpDev2 to set render states, lpView2 to attach a light
  to the viewport, etc...
  If using Execute buffers, the user needs DirectX 3.0-equivalent version
  of these interfaces. To do this, simply call QueryInterface() to retrieve
  "old" versions of interfaces and use these. An example of execute-buffers
  is provided in the sceneEB.c file.
  The dwWidth and dwHeight parameters are the new Width and Height of the 
  rendering surface. The user might need these if using D3DTLVERTEX.
  This function should return TRUE(1) to tell D3DShell that the call was
  successfull. If the function returns FALSE(0), then the execution will
  stop.

  IMPORTANT : The viewport creation is performed by D3DShell, so the user
 	      should not create a viewport.


  - void ReleaseView(LPDIRECT3DVIEWPORT2 lpView2);

  This function is used in conjunction with InitView(...). Its purpose
  is to free and close all memory or instances allocated in InitView(...).
  An interface to the viewport object is passed to that any light that were
  attached to the viewport in InitView(...) can be deleted.

				***
  
  - void UserWindowProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);

  This is the user window procedure. It is used as a normal WindowProc()
  function. This function is called before the D3DShell window procedure
  itself. It enables the user to retrieve menu choices, keystrokes or 
  other messages.
  D3DShell handles many messages which should not be handled by the user
  application. A list of these messages is :
  
  	WM_ENTERMENULOOP, WM_EXITMENULOOP,
	WM_ACTIVATEAPP,
	WM_SYSCOMMAND,
	WM_SIZE, WM_MOVE, WM_SIZING, WM_MOVING,
	WM_PAINT,
	WM_DESTROY, WM_QUIT

  Do NOT return DefWindowProc(...) in this function, as it will prevent
  D3DShell to handle messages by itself.

				***

  - BOOL RenderScene(LPDIRECT3DDEVICE2 lpDev2, LPDIRECT3DVIEWPORT2 lpView2);

  This is where the user does his/her rendering. 
  The parameters passed to this function are interfaces to Direct3DDevice2
  and Direct3DViewport2 objects. The user must use these to perform his/her
  rendering.
  The BeginScene(...)/EndScene(...) pair must exists in this function.

  If using Execute buffers, the user needs DirectX 3.0-equivalent version
  of these interfaces. To do this, simply call QueryInterface() to retrieve
  "old" versions of interfaces and use these. An example of execute-buffers
  is provided in the SceneEB.c file.
  
  The function should return TRUE to tell D3DShell that the call was
  successful. If the function returns FALSE, then the execution will stop.


  These 6 functions must exist, but you don't have to put any code in these. 
  For instance, if you don't want to deal with any user input, the
  UserWindowProc(...) function will typically be empty.  
  You might as well not want to make any use of QuitApplication(), or even 
  InitApplication(). In that case, just put nothing in these.
  The most simple example of an application using D3DShell is the Triangle
  example (see below).


**********************************************
* How do I use D3DShellSetPreferences(...) ? *
**********************************************

D3DShellSetPreferences(...) is a function that can be called from the
InitApplication() function. It is used to pass preferences to D3DShell.
A prototype of the function is :

void D3DShellSetPreferences(char 	*pszApplicationName, 
			    HMENU 	hUserMenuID, 
			    HACCEL 	hUserAccel, 
  			    HICON 	hUserIcon, 
			    enum D3DShellPrefs 	dwFlags);

*pszApplicationName 	is your application name (will appear in the
			application window)


hUserMenuID 		is the user menu handle (can be NULL if no menu is 
			to be used).

			A menu can be loaded from a resource file or created
			manually by the user. If loaded from a resource file,
			the user should use the LoadMenu(...) function to load
			the menu. Example :

			HMENU	hMyMenu;

			hMyMenu=LoadMenu(NULL, MAKEINTRESOURCE(ID_MENU));
			
			The first parameter of the LoadMenu(...) function
			is NULL because you don't need to know the application
			instance (HINSTANCE) to load a menu.


hUserAccel		is the user accelerator table handle (can be NULL 
			if no accelerator table is to be used).

			An accelerator table can be loaded from a resource file
			or created manually by the user. If loaded from a resource 
			file, the user should use the LoadAccelerators(...) function 
			to load the accelerator table. Example :

			HACCEL	hMyAccel;

			hMyAccel=LoadAccelerators(NULL, MAKEINTRESOURCE(ID_ACCELTABLE));
			
			The first parameter of the LoadAccelerators(...) function
			is NULL because you don't need to know the application
			instance (HINSTANCE) to load an accelerator table.


hUserIcon		is the user application icon handle (can be NULL 
			if no icon is to be used).

			An Icon can be loaded from a resource file or created manually 
			by the user. If loaded from a resource file, the user should use 
			the LoadIcon(...) function to load the icon. Example :

			HICON	hMyIcon;

			hMyIcon=LoadIcon(NULL, MAKEINTRESOURCE(ID_ICON));
			
			The first parameter of the LoadIcon(...) function
			is NULL because you don't need to know the application
			instance (HINSTANCE) to load an icon.

dwFlags			is a list of flags that can be passed to control
			the available rendering parameters.
			These flags are :
	
			FORCE_PRIMARYDEVICE : 	Primary device will be used by default (no 
						other DDraw driver will appear in the menu).
			FORCE_SECONDARYDEVICE : Secondary device will be used by default (no 
						DDraw driver will appear in the menu).
			FORCE_ZBUFFER_ON : 	Z-Buffer will be forced On and will not appear in the menu.
			FORCE_ZBUFFER_OFF :	Z-Buffer will be forced Off and will not appear in the menu.
			FORCE_SINGLEBUFFER : 	Single buffer will be forced On and will 
					     	not appear in the menu.
			FORCE_DOUBLEBUFFER : 	Double buffer will be forced On and will 
					     	not appear in the menu.
			FORCE_TRIPLEBUFFER : 	Triple buffer will be forced On and will 
					     	not appear in the menu.
			FORCE_FULLSCREEN :   	Full screen mode will be used all the time 
					     	(Unable to go to window mode)
			DISABLE_SINGLEBUFFER : 	Single buffer choice will not appear in 
					       	the menu.
			DISABLE_TRIPLEBUFFER : 	Triple buffer choice will not appear in 
					       	the menu.
			DISABLE_VERYHIGHRES : 	Disable resolution above 1024x768. This flag 
					      	should be specified if the target hardware is 
					      	a first generation PowerVR board (PCX1, PCX2)
						and using drivers 4.1.1c3 or earlier.
			DISABLE_RESIZING :	Prevent the application to be resized.
			DEFAULT_SECONDARYDEVICE : Secondary device will be selected by default
			DEFAULT_ZBUFFER_ON :	Application will start with a Z-Buffer as default
			DEFAULT_FULLSCREEN : 	Application will start full screen by default.
			FORCE_CLEAR_ON : 	Force the viewport clear before drawing a new frame. If this 
						flag is used, then DISABLE_SINGLEBUFFER should also be used, 
						as you will get flickering on your screen if you run your 
						application single-buffered with its viewport cleared every frame.
						Clear will not appear in the menu.
			FORCE_CLEAR_OFF :	Disable the viewport clear before each frame.
						Clear will not appear in the menu.
			DEFAULT_CLEAR_ON :	Viewport clearing is On by default.
			DISABLE_RAMP_MODE :	Ramp emulation D3D device will not appear in the menu.
			DISABLE_MMX_MODE :	MMX emulation D3D device will not appear in the menu.
			NO_MEMORY_CHECK	: 	Video memory will not be checked, thus attempting 
					  	to create all variables without checking if there 
					  	is enough memory for them.

A global example of using D3DShellSetPreferences(...) is :

D3DShellSetPreferences("My D3D Application", hMyMenu, hMyAccel, hMyIcon, 
			DISABLE_VERYHIGHRES | DISABLE_SINGLEBUFFER | DISABLE_RESIZING | CLEAR_VIEWPORT);


************************************
* What does the D3DShell menu do ? *
************************************

The menu created in D3DShell handles the following rendering parameters :

FILE MENU :

- Screen capture (F12) : Performs a screen capture of the current back buffer.
			 The image is saved as a BMP file named ScreenXX.BMP in
			 the current directory.

- Display Info (TAB) :	 Display information concerning the application (rendering
			 surface dimensions, buffering mode and frame rate).
			 In single buffer mode the text might blink. This is normal,
			 as it is directly blitted onto the primary surface.

- Quit (ALT+F4) :	 Quit the application.


DEVICES MENU :

- Primary device : 	Corresponds to the primary DirectDraw device.
- Secondary device :	This option will be available only if a secondary device exists.

- Ramp Emulation :	D3D Ramp emulation. This can be disabled by an application flag
			(See above).
- RGB Emulation :	D3D RGB emulation.
- Direct3D HAL :	Select this device to use the 3D hardware on your current DirectDraw
			device (primary or secondary if it exists)
- MMX Emulation :	D3D MMX emulation. Will only appear if the system is a MMX system.
			This can be disabled by an application flag (See above).


BUFFERING MENU :

These options are only applicable in full screen mode. In window mode, the application
is always double buffered.

- ZBuffer :		 Z-Buffer On/Off.

- Single buffer :	 No back buffer will be created and PowerVR will directly
			 render onto the visible surface (primary).

- Double buffer :	 Both a back and front buffers will be created. PowerVR will
			 render onto the back buffer and the buffers addresses will
			 be swapped when the rendering is finished.

- Triple buffer :	 Two back buffers and a front buffer are created. PowerVR
			 renders onto the first back buffer, then immediately renders
			 onto the second back buffer when the first is finished. 
			 At the next vertical blanking, the first back buffer is 
 			 displayed by swapping the rendering addresses of the flipping 
			 chain.

- Clear :		 If this option is enabled, the viewport will be cleared before
			 each new frame. In that case, a material colour should be 
 			 assigned to the background first (using SetBackground() D3D function).
			 If this option is NOT enabled, the viewport will never be cleared.
			 In that case, your application should overlap the entire contents
			 of the rendering surface for each frame.
			 Not clearing the viewport results in a gain of performance.

MODES MENU :

This menu handle full screen and window modes, and enable the user to select a
rendering resolution.


*****************************
* D3DShell Helper functions *
*****************************

Two helper functions are provided in the D3D Shell :


- void D3DShellSetDisplayText(char *pszText, int nX, int nY);

This function is used to display a text on the rendering screen. It should be called
in the RenderScene(...) function, before (or after) the BeginScene/EndScene bracket.

*pszText 	is the string to display.
nX, nY 		are the screen coordinates to which the text will be displayed.

This function can be called several times : other calls to
D3DShellSetDisplayText(...) will display a new string up to 50 different strings
on the screen.

Note : This function uses a GDI blit (TextOut(...) function) to display the text.
       For some 3D accelerators that perform scene capture, 2D operations can slow 
       down the rendering process, thus a 3D text display function would be better.


- D3DTEXTUREHANDLE D3DShellLoadBMP(char *lpName, BOOL bTranslucent);

This function loads a BMP texture from a resource or file and returns a handle 
for it. 
IMPORTANT : If loading textures from resource, the BMP resources IDs MUST be strings, 
NOT numbers. 
See the Nefertiti example of how to load textures from resource.
All textures loaded with this function are automatically taken care of by the 
D3D Shell, so the user doesn't have to worry about restoring or releasing these textures.
RGB and OS/2 formats are supported. RLE encoded format is NOT supported by this function.
Does NOT support 4-bit or 8-bit palettised yet.
A future version of D3DShell might have better texture loading facilities.

*lpName		is the name of the texture to load. This can either be the name of 
		a BMP file in the resource, or an actual file name.

bTranslucent	indicates if the texture is used as a translucent texture. If 
		bTranslucent is set (TRUE), then the texture name t+"name"
		will also be looked for. If found, the texture will be created
		in a translucent format, using the red channel of the translucent
		texture to create the alpha channel.

The best opaque and translucent texture formats are chosen by selecting the ones
that have the larger bit depth for each channel of the texture format. For instance,
if both 888 and 565 texture format are supported, 888 will be chosen.


********************
* Triangle example *
********************

TRIANGLE is an example of the simplest D3D application that uses D3DShell. It 
puts a single triangle on the screen.
To build TRIANGLE, create a project and include :

D3DShell.c	Set of functions used to control the rendering
D3DShell.h	Header file for D3DShell.c.
D3DTri.c	The Triangle demo.

Paths set up or explictly included libraries and include files.
DDraw.h		DirectDraw header.
D3D.h		Direct3D header.
DDraw.lib	DirectDraw functions.


*********************
* Nefertiti example *
*********************

Nefertiti is an example of a D3D application that uses D3DShell. It gives an example
of how to use a menu, accelerators table, and icon in the application.
To build Nefertiti, create a project and include :

D3DShell.c	Set of functions used to control the rendering
D3DShell.h	Header file for D3DShell.c.
Newnef.c	Nefertiti file.
Newnef.h	Nefertiti header file.
Newnef.rc,
Nefertt.ico,
Checker.bmp,
Tex2.bmp,
Tex7.bmp,
Win95.bmp	The resource files including icons and textures.

Paths set up or explictly included libraries and include files.
DDraw.h		DirectDraw header.
D3D.h		Direct3D header.
DDraw.lib	DirectDraw functions.

The resource file (.ico and .bmp) are only used for building the application, as
they get included in the application .exe (NewNef.exe) after linking.


-------------------------------------------------------------------------------------------
This document is provided as part of the PowerVR SDK under Non-Disclosure Agreement.
(c) 1998 VideoLogic Ltd.

PowerVR is a registered trademark of VideoLogic Ltd. (United Kingdom). All rights reserved.  
Windows and DirectX are either registered trademarks or trademarks of Microsoft 
Corporation in the United States and/or other countries. 

END OF FILE.








