

SGLShell documentation, 15/05/98

Current SGLShell version : 1.1.4


**********************
* What is SGLShell ? *
**********************

SGLShell is a single C file (with its header) which provides a safe Windows
environment for your SGL Direct-based application.

SGLShell allows the user to change various settings including FullScreen/Window
mode operation, buffering mode and screen resolution at run-time.

It uses SGL address mode to deal with the rendering surfaces. 

DirectX 3.0 or above must be installed to use SGLShell.


***************************
* How do I use SGLShell ? *
***************************

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

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

Paths set up or explictly included libraries and include files.
SGL.h		Access to SGL Functions.
SGL.lib		The SGL Library.


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

  - void InitApplication();

  This function will be called only once by the SGL Shell before anything 
  happens, at the very beginning of the SGLShell 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, setup the
  SGL Context, load and allocate textures, etc...

  Within this function the user can call SGLShellSetPreferences(...) 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(DWORD dwWidth, DWORD dwHeight);

  This function is called each time a rendering variable is changed in
  the SGLShell (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. 
  dwWidth and dwHeight are passed to your application and correspond to 
  the new Width and Height of the rendering surface. The user may need 
  these to create his/her viewport or centering the scene accordingly.
  This function should return TRUE(1) to tell SGLShell that the call was
  successful. If the function returns FALSE(0), then the execution will
  stop.

  - void ReleaseView();

  This function is used in conjunction with InitView(...). Its purpose
  is to free and close all memory or instances allocated in InitView().

				***
  
  - 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 SGLShell window procedure
  itself. It enables the user to retrieve menu choices, keystrokes or 
  other messages.
  SGLShell 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_MOVING,
	WM_PAINT,
	WM_DESTROY, WM_QUIT

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

				***

  - BOOL RenderScene();

  This is where the user does his/her rendering. Typically one would call
  sgltri_startofframe(...) and sgltri_render(...) in this function.
  The function should return TRUE to tell SGLShell 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 ReleaseView(), or even 
  InitView(...). In that case, just put nothing in these.
  The most simple example of an application using SGLShell is the Triangle
  example (see below).


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

SGLShellSetPreferences(...) is a function that can be called in the
InitApplication() function. It is used to pass preferences to SGLShell.
A prototype of the function is :

void SGLShellSetPreferences(char 	*pszApplicationName, 
			    HMENU 	hUserMenuID, 
			    HACCEL 	hUserAccel, 
  			    HICON 	hUserIcon, 
			    enum SGLShellPrefs 	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_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.
			DEFAULT_FULLSCREEN : 	Application will start full screen by default.
			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 SGLShellSetPreferences(...) is :

SGLShellSetPreferences("My SGL Direct Application", hMyMenu, hMyAccel, hMyIcon, 
			DISABLE_VERYHIGHRES | DISABLE_SINGLEBUFFER | FORCE_FULLSCREEN);


************************************
* What does the SGLShell menu do ? *
************************************

The menu created in SGLShell 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.


BUFFERING MENU :

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

- 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.

MODES MENU :

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


******************************************
* SGLShellSetDisplayText (... ) function *
******************************************

A helper function can be called from the application in the RenderScene() function.
A prototype of the function is :

void SGLShellSetDisplayText(char *pszText, int nX, int nY);

This function is used to display a text on the rendering screen.

*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
SGLShellSetDisplayText(...) 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.
       As far as PowerVR is concerned, 2D operations can slow down the rendering
       process, thus a 3D text display function would be better.


int SGLShellLoadBMP(char *lpName, BOOL bTranslucent, BOOL bMipmap);

This function loads a BMP texture from a resource or file and returns the texture
number for it. It just creates an intermediate_map format for a texture, and then
call sgl_create_texture with that intermediate map.
IMPORTANT : If loading textures from resource, the BMP resources IDs MUST be strings, 
NOT numbers. 
See the Logo example of how to load textures from resource.
Textures loaded with this function must be freed bu the user (i.e. call
sgl_delete_texture(...) when releasing the textures).
A future version of SGLShell 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.

bMipmap		indicates if the texture is used as a mipmap textures. All mipmap
		levels are created by SGL in that case.


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

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

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

Paths set up or explictly included libraries and include files.
SGL.h		Access to SGL Functions.
SGL.lib		The SGL Library.

****************
* Logo example *
****************

LOGO is an example of a SGL Direct application that uses SGLShell. It gives an example
of how to use a menu, accelerators table, and icon in the application.
To build Logo, create a project and include :

SGLShell.c	Set of functions used to control the rendering
SGLShell.h	Header file for SGLShell.c.
SGLLogo.c	Logo file.
SGLLogo.h	Logo header file.
SGLLogo.rc,
pvr.ico,
Pvr.bmp,
Reflect.bmp,
Title.bmp,
tTitle.bmp	The resource files including icons and textures.

Paths set up or explictly included libraries and include files.
SGL.h		Access to SGL Functions.
SGL.lib		The SGL Library.


-------------------------------------------------------------------------------------------
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.








