Creación de un motor de render para una plataforma móvil

Size: px
Start display at page:

Download "Creación de un motor de render para una plataforma móvil"


1 UNIVERSIDAD CARLOS III DE MADRID INGENIERÍA INFORMÁTICA GRUPO DE INTELIGENCIA ARTIFICIAL APLICADA Creación de un mtr de render para una platafrma móvil Autr: Tutr: Antni Berlanga de Jesús Fecha: Ener 2008

2 Resumen Ls dispsitivs móviles cada vez tienen más capacidades, pudiend realizar tareas que anterirmente eran exclusivas para rdenadres persnales. Un ejempl de este tip de tareas es la visualización de gráfics tridimensinales en tiemp real. Gracias a la reciente inclusión de prcesadres de aceleración gráfica en ls móviles de gama alta, mstrar gráfics de calidad en un móvil es una psibilidad real, y que presenta múltiples aplicacines. El cmpnente sftware encargad de gestinar la visualización de gráfics tridimensinales se denmina mtr gráfic mtr de render. Si bien existen diverss mtres de render para dispsitivs móviles, n existe un gratuit que psea características cmparables a ls dispnibles para rdenadres persnales. Pr esta razón, vams a migrar un mtr gráfic de códig abiert para PC, llamad Irrlicht, a una platafrma móvil cm es Series 60 3rd Ed. FP1. De este md, crearems un buen mtr gráfic para móviles que pueda ser emplead en psterires trabajs, y prveerems de un detallad cas de us de una migración entre ds platafrmas tan hetergéneas. Abstract Mbile devices have increasing capabilities, and are nwadays able t perfrm tasks that were nce reserved fr persnal cmputers. An example f such tasks is the visualizatin f tri-dimensinal graphics in real time. Thanks t the recent additin f accelerated graphics prcessrs int the high-end devices, rendering high quality graphics is a reality by nw, and it has many interesting applicatins. The sftware cmpnent that is in charge f managing the visualizatin f graphics is usually called a graphics engine, als knwn as render engine. Even thught there are several render engines available fr mbile devices, there is n free ne that exhibits a set f features cmparable t thse ffered by the engines aimed t persnal cmputers. Because f this reasn, we are ging t prt an pen-surce graphics engine fr the PC, called Irrlicht, t a mbile platfrm such as Series 60 3 rd Ed. FP1. This way, we will create a gd graphics engine fr mbile devices that might be later user in ther prjects and, mrever, we will prvide a detailed use case f a prt between tw very hetergeneus platfrms. Page 2

3 TABLE OF CONTENTS 1 Intrductin 6 2 Brief intrductin t 3d graphics engines Graphic APIs / Standards The graphics pipeline OpenGL Direct3D Graphics engine Cmpnents f a graphics engine Elements managed by a graphics engine Techniques used in graphic engines Game engine 20 3 State f the art Mbile 3D graphics/game engines Explred search results Interesting engines fund Mbile 3D graphics APIs OpenGL ES Mbile 3D graphics API (M3G) Direct3D Mbile Mbile perating systems / sftware platfrms Symbian OS Windws Mbile Other perating systems / platfrms Market Study Mbile phnes Phne categries Hardware Perfrmance benchmarks Best mbiles fr 3D graphics Open surce 3D graphics / games engines fr PC OGRE 3D 79 Page 3

4 3.5.2 Irrlicht 85 4 Prblem statement 90 5 Prting Irrlicht Planning Requirements and scpe Prpsed plan / schedule Budget Creatin f the OpenGL ES Driver Creating a new driver Duplicating the OpenGL driver OpenGL ES supprt and EGL Cre functinality Extensin handling Clr handling Creatin f the Series 60 Device Intrductin Creatin f the prject Changes due t the cmpiler Changes t the OpenGL ES driver Creatin f the S60 device Our implementatin Other minr changes Results Prting the dems t S Prject files Utility files Dem mdificatins Running the dems n the N95 8Gb Hell Wrld Quake 3 Map User Interface D Graphics Cllisin 213 Page 4

5 6.2.6 Special FX Terrain rendering Render t texture Quake 3 Map shaders final cmments abut testing Evaluatin Further wrk Cnclusins Bibligraphy 225 Page 5

6 1 INTRODUCTION Just as it happens with cmputers, mbile phnes and handheld devices are getting mre pwerful every day. This means that tasks that were t demanding fr mbile phnes in the past are nw pssible, such as rendering 3D graphics in real time. 3D cmputer graphics are very useful fr different things such as: scientific visualizatin, gaming, surveillance, advanced user interfaces, and s n. Althugh it is nt a requirement, usually the applicatins using 3D graphics has a separate cmpnent fr managing them, the s-called 3D graphics engine. Furthermre, a 3D graphics engine usually is general enugh s that it suits several applicatins. There are several 3D graphics engines fr applicatins aimed fr mbile phnes, but mst are cmmercial and, the free nes, lack mst f the features that can be fund n the engines aimed fr persnal cmputers. Because f this, we are ging t prt a gd pensurce engine aimed t persnal cmputers, Irrlicht, t a platfrm used in many mbile phnes: the Nkia Series 60 3 rd Editin FP1 platfrm. The fllwing pages describe the prcess f such prject. We will begin with a shrt intrductin t the wrld f 3D graphics. It will briefly explain the cncepts needed t understand the basics f 3D graphics, what a graphics engine des and hw, and which features can differentiate ne engine frm anther. Afterwards, an in-depth research f the state f the art f the technlgies related t this prject will be presented. These technlgies include 3D graphics engines fr bth persnal cmputers and mbile phnes, mbile 3D graphics APIs, perating systems, platfrms, and hardware, all f them used in mbile phnes. The next sectin will just be prblem statement, that is, a descriptin f what is ging t be dne in this prject. Fllwing it, the bigger sectin f this dissertatin cmes. A planning is dne fr the prject, and then executed, cmmenting all the steps fllwed s that they can be repeated, if smene wants t d s. After that sectin, we cmment the results, what culd still be imprved and ur cnclusins abut the prject. Finally, an extensive bibligraphy with all the bks, articles and web pages frm which sme infrmatin was taken is prvided. During these sectins, n previus knwledge abut 3D cmputer graphics r Symbian develpment is assumed. Because f that reasn, readers familiar with them might want t skip the sectin 2 (in the case f cmputer graphics) r sectins t Page 6

7 2 BRIEF INTRODUCTION TO 3D GRAPHICS ENGINES In rder t understand this dissertatin, sme knwledge abut the main cncepts abut 3D graphics engines is needed. As it always happens, there is nt a single bk that cvers every aspect f 3d game engines, as it is quite a big tpic. Hwever, there are many bks n the tpic f 3D graphics, such as [1] which ffers a general verview, with certain fcus n OpenGL- r the excellent [2] which is mre fcused n the mathematics behind 3D graphics -. In thse bks, the cncepts related with 3D graphics in general are explained in great detail. Hwever, in rder t understand a 3D graphics engine, this is nt enugh. Apart frm dealing with graphics, a cmplete graphics engine perfrms als memry management, has lw-level ptimizatins (fr example, by using SIMD CPU instructins when available t speed up mathematical peratins) and, in general, uses sme specific techniques and algrithms that are nt addressed by bks fcused just in 3D graphics. In rder t have an verview abut thse techniques, any bk abut creating game engines wuld be valid -because as we will see later, a game engine usually cntains a graphics engine, as every game shws sme graphics-. Gd bks abut this tpic are [3] which explains a typical architecture f a cmplete game engine-, and the highly recmmend [4] which ffers a mre practical apprach, as it explains step by step hw t build a 3d game engine frm scratch-. In the fllwing sectins, we will explain the mst imprtant aspects f 3D graphics engines just up t the detail needed t understand this dissertatin. In case f wanting t read mre abut them, please refer t any f the bks already presented in this sectin. 2.1 GRAPHIC APIS / STANDARDS In rder t begin in the field f cmputer graphics, it is imprtant t understand the rle f the graphics pipeline, the different graphics API, the graphics engines and their differences with game engines. The fllwing sectins will address that issues THE GRAPHICS PIPELINE The data representing a scene has t undergne certain transfrmatins and prcessing steps until the scene can be actually being rendered n the screen. Thse transfrmatins cnfrm what is usually called the graphics pipeline r rendering pipeline, as it is smetimes referred. Page 7

8 By using a graphics API, the user is able t input data t the pipeline a prcess infrmally called feeding the pipeline- and in return it gets an utput, usually in the frm f an image. A typical scheme f a pipeline can be seen in the fllwing illustratin: Applicatin vertices Vertex assembly primitives Vertex peratins Primitive assembly Primitive peratins Rasterizatin Fragment peratins Framebuffer Display Illustratin 1. Schematic view f a typical 3d graphics pipeline. In this case, a fixed pipeline. The different peratins perfrm at the different stages are: Vertex assembly. Cnverts the input data int an internal representatin and initializes unspecified values. It als perfrms errr detectin. Vertex peratins. Transfrms crdinates, cmputes lighting and texture crdinates. Primitive assembly. Grups vertices int primitives (pints, lines, triangles, quads, plygns ), decmpses plygns int triangles and duplicate vertices in strips and fans. Primitive peratins. Clips the primitives t the viewing vlume, perfrms backface culling if enabled and assign clrs fr tw-side lighting. Rasterizatin. Determines which pixels are included in each primitive generating a fragment per each- and assign attributes t them. A fragment is just a pixel that is nt in the framebuffer and has certain added infrmatin such as depth infrmatin. Fragment peratins. They are texture mapping assigning texels t fragments-, fg, scissr and alpha tests. Framebuffer: Operatins dne t transfer a fragment t the framebuffer. Thse are clr blending, wnership test and depth test. Nte that the actual peratins perfrmed at each step can vary between pipelines, and that even the stages shwed here are the results f just ne f the multiple abstractins Page 8

9 pssible. Indeed, the cmplete OpenGL 1.1 pipeline, fr example, is as cmplex as can be seen in the fllwing image: Illustratin 2. OpenGL 1.1 graphics pipeline. Image taken frm a webpage 1 f the specificatin index. Furthermre, if we g a step further, we will see that in hardware the graphics pipeline culd be cmpletely different althugh it has t prduce the same results-, fr example: 1 Page 9

10 Illustratin 3. Architecture f a NVIDIA GeFrce Image taken frm curse slides f Kurt Akeley. Thrugh the a Graphics API, the user cannt nly prvide input data (vertices and primitives) t the pipeline, but he/she can als manipulate the states f the pipeline t vary the way the infrmatin is handled and he might even be able t prvide sme cde t be used inside it. In fact, this leads t the main classificatin f the different graphic pipelines: fixed pipelines, and prgrammable pipelines. A fixed pipeline is just what we saw in the previus illustratin and behaves as we explained then. A prgrammable pipeline fllws a similar scheme but, hwever, it behaves differently as what it des in the vertex peratins, primitive peratins and fragment peratins can be prgrammed by uplading prgrams usually called shaders. The fllwing illustratin shws this: Page 10

11 Applicatin vertices vertex shaders primitives Vertex assembly Vertex peratins Primitive assembly gemetry shaders Primitive peratins Rasterizatin pixel shaders Fragment peratins Framebuffer Display Illustratin 4. Scheme f a prgrammable pipeline. We have used the DirectX terminlgy, which is the mst cmmn ne. In OpenGL, hwever, vertex shaders are called vertex prgrams, gemetry shaders are called just the same, and pixel shaders are called fragment prgrams. Gemetry shaders are quite a new feature, being nly supprted by the DirectX 10 API and OpenGL 2.0 thrugh an extensin. The first graphic card supprting them was the NVidia GeFrce Nw that we have seen a scheme f a graphics pipeline, it is time t see the tw majr graphics APIs available fr persnal cmputers. We will intrduce them briefly there are plenty f bks and resurces n the Internet abut each f them- just s that it is clear what we are referring t in the future OPENGL OpenGL is a 3D graphics API that was develped by Silicn Graphics Inc (SGI) in Up t that date, the nly way f cmmunicating with the graphics hardware was t use prprietary APIs prvided by the hardware vendr. This was making very difficult and cstly t build applicatins capable t run in a variety f different hardware. By that time, SGI was leader in the 3D graphics market and their library, called IRIS GL, was the de-fact standard. Hwever, as mre and mre cmpanies entered the graphics market, the influence f SGI started t weaken. In rder t avid that situatin, SGI decided t turn IRIS GL int an pen standard: OpenGL. The reasns why OpenGL triumphed ver ther APIs such as PHIGS (which was based entirely n pen standards) was that it was easier t use and, abve all, because f its supprt fr immediate mde, which allwed fr higher perfrmance tuning pprtunities. That means that in OpenGL, primitives are send fr drawing t the underlying hardware, and the scene Page 11

12 management is left t the applicatins, giving them mre freedm. In retained mde, hwever the ppsite f immediate mde, which is what PHIGS used- the scene management is perfrmed by the library, which can be less ptimized due t its lack f particular knwledge abut the applicatin. When OpenGL 1.0 was released, a grup f cmpanies interested in its develpment frmed the s-called OpenGL Architecture Revisin Bard (OpenGL ARB) which was meant t be respnsible fr the maintenance f the API and its evlutin (OpenGL 2.0, OpenGL 2.1). Amng the changes intrduced by these versins, the mst imprtant ne was the intrductin f shaders int OpenGL, thus replacing the fixed pipeline by a prgrammable pìpeline. On September f 2006, the cntrl f OpenGL was passed t the Khrns Grup (which was respnsible fr the OpenGL ES API). The first release after this change has been the 3.0. This released had been largely awaited. Hwever, it has been heavily criticized since its release n August f 2008, as it des nt include sme f the changes that had been annunced. One f the reasns fr this is that the plicy fllwed by Khrns with respect t OpenGL is nt t break backwards cmpatibility. Amng the best features f OpenGL there are the fact that it is an pen standard which can be supprted by any platfrm and its extensin system (which allw different implementers t add new functinalities t the API) DIRECT3D Direct3D is the ther mst successful graphics API. It was released by Micrsft in 1995, after they bught RenderMrphics, a cmpany that had develped a 3D graphics API fr medical imaging and CAD sftware. At first, Direct3D was nt very liked by the prfessinals f the sectr, due t its difficulty f use and cmplex design. Indeed, several renwned develpers asked Micrsft t abandn Direct3D and fcus n OpenGL. Micrsft, hwever, decided t imprve their API, nt just t cmpete with OpenGL but als with ther APIs such as Glide (created by 3dfx). Albeit thse hard beginnings, Direct3D (which is released as part f the DirectX API cllectin) has gained ppularity in the last years (especially in the 2000s) as Windws heavily utnumbers all the ther platfrms when it cmes t gaming. The main differences between Direct3D and OpenGL, apart frm the API itself, are that Direct3D des nt supprt extensins and that it is a prprietary standard available nly in Windws platfrms. Cncerning features and perfrmance, it is very argued which ne is better, but the mst cmmn pinin is that the same functinality can be achieved with bth f them with mre r less the same perfrmance. Page 12

13 2.2 GRAPHICS ENGINE As it has been said, a graphics API defines a set f lw-level rutines that can be used t generate cmputer graphics withut wrrying abut the underlying hardware. Hwever, fr big graphic-extensive applicatins this is nt enugh. Think fr example in a vide game, where each mdel t be rendered can have thusands f triangles. Calling the graphic API rutines fr each f them every time they must be rendered can be very tedius and inefficient. What is usually dne is t create rutines that can handle an entire mdel, by calling itself the apprpriate graphic API rutines. Other cmmn prblem is related with memry management. In a single screen f the game, several instances f a single mdel r texture might need t be rendered. In rder t maximize perfrmance, it shuld be avided t lad each mdel / texture every time is ging t be used, but nly the first time cnsequent references t them can use the already laded texture / mdel. Anther thing t cnsider is that, as cmputer graphics make extensive use f mathematics, it is als a gd idea t pack tgether all the cde needed t perfrm the cmmn mathematic peratins. This way, the same cde can be called and thus reused- frm everywhere it is needed. Mrever, as this cde is very frequently used, it is a perfect candidate fr lw-level ptimizatin, which culd be very difficult and tedius in the case f having the cde scattered all acrss the applicatin. Finally, it might be needed t create an applicatin that is graphics-api-independent (able t wrk with several APIs). In this case, having all the graphics-related cde f the applicatin is crucial t avid adding branches in every API rutine call and ending with the scalled spaghetti cde. The piece f sftware respnsible f dealing with all this prblems, and many thers, is the graphics engine COMPONENTS OF A GRAPHICS ENGINE There is nt a frmal list abut what a graphics engine needs r des nt need t d. It has just t prvide an abstractin layer between the graphics API and the applicatin cde. In general terms, hwever, a graphics engine can have: A specific-purpse, ptimized mathematical library. A lw-level subsystem in charge f dealing with memry allcatin, endianness and ther lw-level details. Resurce laders, able t lad resurces (textures, mdels) frm external memry in several frmats Scene management, in charge f defining spatial hierarchies f the bjects in the scene t be rendered, needed t rganize the infrmatin s that it can be managed efficiently. Page 13

14 Special effects supprt, t create visual effects that are nt directly supprted by the graphic APIs, such as bump-mapping, envirnment-mapping, stencil shadws, etc. Animatin supprt, t handle animated bjects. A graphical user interface. Etc. Nte again that this is nt a clsed list. In additin, sme f the elements abve might be used in ther engines apart frm the graphics engine (such as the scene management and the math library, which might be als used by a physics engine). In thse cases, the cmmn elements use t be mved ut f the engine ELEMENTS MANAGED BY A GRAPHICS ENGINE N matter hw simple a graphics engine culd be, there are elements that it will need t handle in rder t create real-time graphics. These elements will be explained briefly in the fllwing lines Mdels The mdels are the gemetry f the scenes, the 3D bjects. A mdel is cmpsed f vertex data (that is, a set f vertices and the type f primitive it describes i.e. pints, lines, triangles, quads, plygns, etc -). Nt nly the psitin f each vertex can be prvided, but als its nrmal vectr, texture crdinates, a clr, material prperties, etc. This data can be used later when applying textures r lighting, fr example Textures Traditinally, textures were images that were mapped t the gemetry in rder t add additinal details in terms f clrs withut needing extra plygns. Hwever, new texture mapping techniques have been develped that allw 1D and 3D textures instead f nly 2D images. Mrever, new mapping techniques such as bump mapping r ambient cclusin mapping d nt use images as input, but ther data that allws imprving the appearance f the gemetry in different ways. Textures can even be used t identify different parts f the gemetry fr prcedural animatin e.g. the hit maps used in Dm 3-. Usually, mre than ne texture can be used in a single mdel. Because f these reasns, nwadays textures are nt just 2D images, but any set f data that can be used during the rendering prcess. There are several types f textures, accrding t their purpse. A gd althugh smehw bslete- taxnmy created by Sean Barret can be fund in [5]. Frm it, the mst imprtant types are: Diffuse map. It defines the clrs f the surface. Technically, clr is a visual perceptual prperty, which means that it is subjective. What a diffuse map really Page 14

15 specify is the albed (the rati f diffusely reflected t incident electrmagnetic radiatin). This map can be seen as an image; this is the traditinal usage f textures. Detail map. It is a special type f diffuse map, which is scaled dwn with respect t the gemetry and is repeated at high frequency. Specular map. It specifies the specular respnsiveness f a given surface. Emissive map. It specifies which parts f the surface emit light independently f external light surces. Light map. It specifies which parts f the surface are lit by the light f the cmplete scene and with which intensity, i.e. this is pre-calculated lighting. T be useful, lights accunted during the creatin f the map shuld be static with respect t the surface. Reflective envirnment map. It specifies hw the envirnment is seen frm an bject r the rigin f the scene. They use t be either a 2D image an sphere map, fr example- r mre cmmnly a cube map a cube, where texture data is lcated n its inside faces-. Envirnment maps are used t make bjects appear reflective. Bump/displacement map. It specifies a height variatin fr each pint f the surface. Nrmal map. It specifies the nrmal vectrs fr each pint f the surface. Once mre, there are mre types f textures than the nes listed here, and many thers are likely t appear in the future Lights The eye perceives bjects thrugh the light they emit r reflect. Because f that reasn, understanding lighting is ne f the key aspects in 3D graphics. Unfrtunately, real wrld light is quite cmplex, and it is really hard t simulate it; even impssible when it cmes t real-time graphics as f tday. Because f this reasn, a series f simplificatins have t be made, resulting in a cncrete lighting mdel. In the calculatins used t lighten a mdel, when using the Blinn-Phng reflectin mdel, fur main cmpnents f light are taken int accunt: Ambient light. It is the clr and intensity f the light that evenly lightens every pint f every mdel in the scene. It simulates the light that is reflected and scattered in all directins that cmes frm every light surce. Diffuse light. It is the clr and intensity f the light that is diffusely reflected. Diffuse reflectin is the term used t refer when each light ray is reflected in several directins and angles due t uneven r granular surfaces. Specular light. It is the clr and intensity f the light that is perfectly reflected. That is, the angle f incidence with respect t the nrmal vectr f the surface is the same as the angle f reflectin. Emissive light. It is the clr and intensity f the light emitted by the bject. Page 15

16 There are als different kinds f light surces that are cnsidered in lighting mdels. The mre cmmn are: Pint light. A light surce in which rays riginated in ne pint are casted in all directins. Pint lights have clr and psitin, but nt directin. They have als a given range and attenuatin equatin light intensity is decreased with distance-. A light bulb can be mdeled as a pint light. Directinal light. A light surce where rays are casted parallel the rigin is the infinite- in ne directin and with a certain clr. There is nt a range r attenuatin assciated t this kind f lights, which make them cmputatinally simple. This kind f light is useful t mdel the Sun, fr example. Spt light. A light surce in which rays are casted frm a single pint and riented in a given directin. Light emitted frm a sptlight is made up f a bright inner cne and a larger uter cne, with the light intensity diminishing between the tw. Spt lights have fallff, attenuatin and range, thus being the mst cmputatinally expensive lights. It can be used t mdel the light f a flashlight, fr example. Nte that any f this is written in stne. Different lighting mdels with different lighting equatins can be used thanks t the extensibility prvided by the vertex and pixel shaders-. In fact, it is quite cmmn t d s in nwadays games and engines in general Shaders Shaders are sequences f sftware instructins that are used by prgrammable graphics pipelines during rendering. They are usually executed inside the GPU instead f the CPU, s they allw fr certain degree f parallelism. There are three main types f shaders, which in rder f appliance are: Materials Vertex shaders. A vertex shader is run nce per vertex, and it can change its prperties such as psitin, clr and texture crdinates. It is, hwever, unable t create new vertices. Gemetry shaders. This kind f shader can add and remve vertices frm a mesh. Pixel shaders. These shaders are applied t fragments nt pixels. Fragments are pixels resulting frm the rasterizatin prcess prir t be written in the frame buffer. They have depth infrmatin and there might be several fragments per final pixel-. The shader is applied nce per fragment, thus being useful fr perpixel-lighting, bump-mapping, reflectins, etc. Materials are cllectins f textures, shaders and any ther prperties that can be used t simulate the real wrld material a certain mdel is made f. This cncept is nt nly used in graphics engines. Fr example, in games, it is usually extended t have physical prperties such as frictin, elasticity r weight that are used by the physics engine. Page 16

17 Animatins Animatins are used t simulate mvement r variatins f the bjects represented in the scene. Techniques used in animatin can be classified in tw main types: explicit and implicit techniques. Explicit methds stre the infrmatin and prperties f each vertex f the mdel fr every frame r fr sme f them nly- f each animatin. Implicit methds usually emply skeletns a hierarchy f bnes and jints- fr animatin. The cnfiguratin f the jints define the exact psitin f the entire mdel in a frame, thus animating the skeletn nly define the entire animatin f the mdel. All f these methds require certain infrmatin that must be managed by the graphics engine. Fr example, a graphics engine shuld be able t retrieve animatin data frm specialized files TECHNIQUES USED IN GRAPHIC ENGINES In this sectin, we will explain certain algrithms and techniques used in graphics engine. It will be helpful fr us t knw abut when we research abut the state f the art f 3D graphics engines later. A very gd, intrductry but cmprehensive bk abut the tpic f techniques in game prgramming including many techniques used in graphics engines- is [6] Shadws We explained sme lines ag that lighting is ne f the mst imprtant aspects f 3D graphics, since light is what allw us t perceive the wrld thugh ur eyes, and where there are lights, there are shadws. This is the reasn why rendering realistic shadws is very imprtant, and the techniques fr ding s are imprved with every new engine that is released. There are tw pssible types f shadws, dynamic and static. A dynamic shadw is ne that changes as the light surce r the bject casting it vary. A static shadw, hwever, remains always the same, and thus can nly fr static bjects that are nly affected by static lights. The static shadws have a great advantage ver the dynamic shadws: they can be precalculated, s n real-time calculatins are needed but the nes fr applying them (which can be dne by using the multi-texture functinality f mst APIs). Stencil shadws are mre interesting. There are different methds f achieving them, depending n hardware supprt and the level f realism that is desired. The mst cmmn technique used fr dynamic shadws althugh there are ther less pwerful nes- is called stencil shadws. Basically, shadw vlumes are created by extruding the silhuette f the different elements f the scene in the directin f the light surces, and then, by using the stencil buffer, it is pssible t knw which areas are in shadw and which are nt. Stencil shadws Page 17

18 were first prpsed by Tim Heidmann in [7], and many imprvements have been made t the algrithm since then (being prbably the mst imprtant the ZFail versin f the algrithm, which slves certain imprtant issues f the riginal ne, called ZPass methd) Scene management As we have said befre, a graphics engine has nly t send the elements f a scene (the gemetries, the textures) t the hardware via the graphics API in rder t get it rendered. Hwever, ding just this wuld be wasteful, as pssibly nt all bjects are visible frm the camera pint f view. Mrever, this culd even yield incrrect results if the rder in which the elements are sent is nt the crrect ne (transparent elements impse rder restrictins: they must be rendered frm back t frnt after all the ther elements, s that transparency is handled crrectly). In rder t avid thse situatins, the elements f the scene have t be managed crrectly, s that elements that are nt ging t be visible are nt even sent t the graphics pipeline and s that the elements are rendered in the ptimal rder. Scene management is dne by using certain data structures and algrithms. The data structures mre cmmnly used are: Binary Space Partitining trees, Quadtrees and Octrees. They are trees that divide the space recursively in tw, fur and eight sub-regins respectively. Prtal engine. This structure is useful fr rendering sets f rms r sectrs cnnected by prtals. Three main peratins might be dne t the elements f a scene prir t send them t render: remving thse elements which are nt ging t be visible (clipping and culling), chsing the required level f detail fr the visible bjects, and srting the elements t maximize perfrmance. Cncerning culling, there are different techniques, being the mre imprtant tw frustum culling and cclusin culling. Frustum culling remves thse elements that are utside the viewing frustum which are, thus, nt visible. Occlusin culling remves thse elements that, albeit lcated inside the viewing frustum, are nt visible because there are ther elements between the camera and themselves. Cncerning selecting the level f detail, this prcess is respnsible fr simplifying the elements that are far frm the camera, reducing the amunt f wrk needed t render them. Fr example, a highly detailed (with a great amunt f plygns and big textures) mdel can be used fr an element when it is clse t the camera, while a lwer detailed ne (with far less plygns and small textures) can be used fr the same element when it is far enugh t guarantee that the difference is nt perceivable. Page 18

19 Finally, abut srting, it is imprtant t take int accunt nt nly transparent bjects (fr the reasns explained befre) but als t send tgether bjects than share textures r ther characteristics s as t minimize the number f state changes in the graphics API Special Effects and ther techniques There are sme effects that require sme special algrithms t be achieved. Examples f thse effects are snw, fire, explsins... these effects are achieved by using a particle system. A particle is an element that can be emitted frm a particle emitter and affected in different ways during the simulatin (by changing the directin in which the particle mves, its clr ). Typically, particles are just simple images rendering n a quad, but they culd be whatever is desired. Other effects might be lens flares, fr example. A lens flare can be simulated by using a billbard. A billbard is just an image that is rendered n a quad which is updated every frame s that it always face the camera. A Billbard system can als be used as a way f level-fdetail if elements far away frm the camera are replaced by simple billbards instead f using their gemetry. Billbards used this way are called impstrs. Reflectins are ther traditinal special effects. Cmputing real reflectins is quite expensive in terms f the peratins needed, s different algrithms are used t apprximate them. Algrithms fr ding s invlve mapping a texture f the envirnment (a cube-map r a sphere map) in a psitin dependent n the viewer psitin, effective simulating actual reflectins. There are many ther pssible special effects, such as mtin blur, blm, depth f field, nrmal mapping, ambient cclusin, refractin, caustics, etc Animatin The different techniques used fr animatin in 3D graphics can be divided int tw types: explicit and implicit methds. Explicit methds stre the infrmatin abut the mdel status in each frame. They are memry-expensive, but require little t nne calculatins; just retrieving the infrmatin fr the current frame is needed. Implicit methds, hwever, use higher-level descriptins f the animatins, generally invlving the cncept f the skeletn. A skeletn is a set f bnes and jints. Vertices f the mdel are psitined in reference with bnes, and the psitin f the bnes themselves depends n the cnfiguratin f the jints. Thus, describing hw the parameters f the jints vary can be used t animate the entire mdel. The mvement f ne element f the skeletn might affect the psitin f thers. Fr example, changing the psitin f a shulder is likely t change the psitin f the arm als. Because f this reasn, a skeletn can be seen as a hierarchy. The advantages f this apprach are a lwer memry ftprint and greater flexibility. Hwever, it is far mre cmplex and CPU intensive. Sme f the mst famus animatin techniques are: Page 19

20 Explicit methds Frame animatin. Infrmatin abut the prperties f the animated mdel is stred per each frame. Key frame animatin. Infrmatin abut the prperties f the animated mdel is stred fr sme frames (key frames). The values used in each frame are interplated frm the data f the tw clser key frames. The interplatr used might vary, frm linear t mre cmplex nes. Implicit methds Frward kinematics. Changes in psitin are prpagated frm base ndes t 2.3 GAME ENGINE terminal ndes. Taking a human being as reference, changing the psitin f the pelvis wuld change the psitin f the legs and feet. This allws fr great cntrl n the final animatin, and can be used with mtin capture data. Inverse kinematics. Changes in psitin are prpagated frm terminal ndes t base ndes. This apprach allws specifying the exact psitin f the terminals in exact psitins; fr example, in rder t have a human walking in uneven terrain crrectly. Hybrid appraches. As frward kinematics allw fr a mre natural mvement specially when cupled with mtin capture data- and inverse kinematics mre adaptability, techniques t mix bth have can be used t have the benefits f bth. Finally, it is imprtant t highlight the difference between graphics engines and game engines. Games engines are used within videgames, ne f the mst spread applicatins that make use f graphics engines. In videgames, nt nly bjects must be shwn in the screen t the user (in real time), but als have t behave realistically and must respnd t the user interactins. The cde that allws all these is what is called a game engine. In general, a game engine has: A cre system, which is respnsible fr dealing with mathematics, files, attributes, and bjects A graphics engine, which is respnsible fr shwing elements in the screen. A physics engine, which is respnsible fr making bjects behave and mve accrding t the real-wrld physics laws. An AI engine, which is respnsible fr generate intelligent respnses fr the NPCs (Nn-Player characters). An audi engine, which is respnsible fr managing the music and the sund effects A netwrking engine, which is respnsible fr prviding multiplayer supprt An input engine, which is respnsible fr allwing the user t interact with the game by using several input devices, such as keybards, mice, jysticks, etc. After reading such a big list, the reader might be wndering what is utside the game engine. It turns ut; hwever, that accrding t [4] a game engine must nly have cde that is Page 20

21 game-independent (that is, the game engine must be reusable between games with sme level f resemblance, it wuld be difficult fr a game engine designed fr a flight simulatr t be used within a FPS, fr example). Cnsequently, the cde that lads the specific game mdels, the scripts that lead the AI, the cde fr specific events within the game, the cde fr features specific t the game, the actual mdels and levels f the game, etc, are utside the game engine itself. Als, nte that these cmpnents are just a way f cnceptually splitting a cmplete game engine, which might nt have an exact mapping with the cde distributin. There might be a game engine that has a different library fr each cmpnent, while ther might have the cde f all cmpnents tangled tgether, in a mre mnlithic fashin. Finally, we wuld light t highlight that, as it happened with the graphics engine list f cmpnents, nt all cmpnents f the list abve are present in every game engine. Fr example, there is n need fr the netwrking engine in games which des nt ffer multiplayer game mdes. On the ther hand, ther cmpnents culd be present inside the game engine. Page 21

22 3 STATE OF THE ART As it has been already said, the gal f this dissertatin is t create a free 3D graphics engine fr mbile phnes, which shuld be able t represent any real-wrld places as realistically as pssible in real time. After researching the state f the art f mbile 3D graphics engines, we fund that as f the time f starting this dissertatin there was nt any engine f that characteristics available, which encurage us t create a new ne. Hwever, creating a new engine des nt necessarily mean building it frm scratch: it might be pssible t prt a 3D pen-surce graphics engine aimed fr persnal cmputers t a handheld device. T determine whether this pssibility was available, research n that field was als dne, with psitive results. The next step was t analyze the state f the art cncerning mbile phnes themselves and the related technlgies available fr develping fr them, in rder t set a precise gal fr the prject. Cncretely, it had t be specified which graphics API t use, which platfrm t target, and which device t use as reference fr the new graphics engine. It is very imprtant t cunt n reliable and in-depth infrmatin prir t taking these decisins, because the effrt needed t develp the new engine, the tls available t d s and the features f the engine depend heavily n them. Mrever, being unaware f the limitatins f the different ptins might lead t taking a wrng decisin that culd result in the cmplete failure f the prject in future stages f develpment r even when deplying it int a real device fr example, if the security mdel f the platfrm prevents the engine frm being installed in an actual phne-. Because all f these reasns, a cmprehensive research was made, resulting in the findings that are shwn in the fllwing sectins. 3.1 MOBILE 3D GRAPHICS/GAME ENGINES Firstly, we searched fr infrmatin abut graphics/game engines in tw different places: [8], and GameMiddleware.rg [9]. Surprisingly, it turned ut that, albeit being very reputed sites abut the tpic f graphics/game engines, mst f the results btained where incrrect r unrelated t the search. After that, we searched fr pen-surce 3D games fr mbile phnes by using Ggle, as they might have ther 3D graphics engines that culd be suitable fr ur purpses (which was very unlikely, anyway). N much interesting results were fund, but sme f them might still be useful. What fllws is a list f all the explred results f the search will be shwn in the fllwing lines, including whether the result was an pen-surce (frm which it wuld be pssible t take cde and ideas) engine r nt. Afterwards, in the next part, we will cmment the features and characteristics f each engine separately. Page 22

23 3.1.1 EXPLORED SEARCH RESULTS Prduct / Enterprise Mbex 3D TORUS The prducts that may be suitable fr ur purpses are highlighted with special brders. Website gines/engine_details.php?id= gines/engine_details.php?id=2 93 Cmments Website under cnstructin. Frm the data f, it is free, and the price is nt public. Website under cnstructin. It seems t be free, but unreleased. Mre infrmatin nt available. ShiVa The standalne engine (which cannt be used t develp, as it is mre a platfrm than a real engine) is free (but nt pen surce). Develpment tls are nt. Exit Games Neutrn 5.0 They d nt ffer a graphics engine, but a multiplayer games platfrm. Ex Machina Their engine is fr quiz games nly. HerCraft HiTech MbileDragn Ideawrks 3D Airplay IN-FUSIO EGE System J2X Technlgies Ncturnal m/technlgy.html m/prducts.htm Free, pen surce mbile 3D graphics engine. Nn-free mbile SDK, which includes a 3D engine. Mre infrmatin can be fund in an appendix f [10]. Nn-free mbile SDK. hp They d nt ffer a graphics engine, but fr GB Advance. Qualcmm Develpers f BREW. They d nt ffer a graphics engine. Pixelgene It was acquired by Rvi in April It is nt free. ndware Richmtin Live Sny Ericssn Nt available They d nt ffer a graphics engine. It was a platfrm fr develping multimedia cntent fr mbile phnes, nt a graphics engine. Develpers f the UIQ platfrm. They d nt ffer a graphics engine. TerraPlay Terraplay has been acquired by End2End Cntent Services in Octber They d nt ffer a graphics engine. Tira Wireless They d nt ffer a graphics engine. GLQuake and Quake II fr Symbian Prt f the quake I and II surce cde t run n the S60 platfrm. Includes the cmplete game engine surce. Page 23

24 3.1.2 INTERESTING ENGINES FOUND The fllwing engines can be cnsidered interesting as they might be used as reference fr ur prject, r even t prvide sme cde r ideas fr it. Because f that reasns, we will them in mre detail HerCraft HiTech MbileDragn MbileDragn is an pen-surce graphics engine develped by HerCraft HiTech. It is crss-platfrm, being able t be run in Windws Mbile 2003 Pcket, Windws Mbile 2003 Smartphne, Symbian OS 6, 7, 8, and Palm Os 5.x. Apart frm that, its main features are: Sftware 2D / 3D Renderer. It supprts Z-buffer, Guraud shading, alpha-blending and perspective crrectin. 2D / 3D sprites supprt. Level f Detail (LOD). Prtal system. Animatin supprt. Bth jint animatins and mrphing. Particle system. 3D Studi MAX exprter. This is actually a disadvantage, as 3D Studi MAX is quite expensive sftware, and n ther methd fr creating 3D mdels fr the engine is prvided. Surprisingly, and despite f this great list f features, the dems included within the distributin are all but impressive, as it can be seen in the fllwing screenshts. Prbably this is because they are meant t be run in lw-spec mbiles. It is wrth mentining that the prvided dems fr Symbian culd nt be installed int an actual phne running Symbian OS S60 3 rd Editin FP 1. Dems wuld need t be recmpiled t d s and, in the wrst case; there is even the pssibility that sme cde f the engine wuld need t be changed. Illustratin 5. Screenshts frm the dems MbileDragn engine, running under Windws XP. Page 24

25 The engine cmes with Dxygen dcumentatin and the surce cde f the dems. The license under which the cde has been released is, hwever, nt publicly stated, s it wuld be needed t the authrs abut it in case f wanting t use the engine GLQuake Game Engines fr Symbian OS The Quake Engine first appeared in the game Quake. Quake was a first persn shter game released by Id Sftware in June 22, It was the mst advanced game f its time, pushing the limits in what cmputer graphics and netwrking fr games is cncerned. Nevertheless, it was the first t be playable ver the internet and t have true 3D graphics (previus games are what were called 2.5D games, as they used many 2D tricks). In rder t be able t cpe with large 3D maps in the hardware that was available at the mment (50 t 75 MHz CPUs), the Quake engine was much ptimized. Amng its features, there are: Efficient map handling by using BSP and PVS: In rder t handle maps efficiently, it uses binary space partitining (BSP) and ptentially visible sets (PSV). Basically, every map (the static gemetry f a scene) is pre-prcessed by an applicatin that generates the BSP and, fr each area f the map, cmputes which ther areas are visible and which are nt, thus creating the PSV. This way, whenever a new render has t be dne, the engine is able t discard thse areas that were nt visible frm where the camera is lcated, saving the time that wuld have been wasted in making the calculatins fr thse areas that, anyway, wuld nt have been shwn. Mre infrmatin abut BSP and PSV can be fund in [11], and infrmatin abut the whle prcess, explained by ne f its authrs Michael Abrash- is available in [12]. Static lighting fr static bjects and Guraud shading fr mving bjects. Apart frm cnstructing the BSP, in the pre-prcessing f the maps, lighting is als calculated and stred in the map file, thus aviding calculating it at real time. Sftware and OpenGL renderers. The riginal Quake engine had a sftware renderer nly, but accelerated hardware supprt by using OpenGL was added later in a new versin f Quake, called GLQuake. Animatin supprt. The engine supprts per-vertex animatin. Animated mdels are stred in MDL files. Particle system. The successr f the Quake engine is the id Tech 2 engine (that was frmerly knwn as Quake II engine). It appeared fr the first time in the Quake II game, which was released by Id in December 9, Again, this game imprved the state f the art f the graphics f the games f its time. Id Tech 2 has ut-f-the-bx supprt fr OpenGL (althugh it still has a sftware renderer, as there were still many cmputers withut OpenGL and hardware acceleratin by the time it was released). Page 25

26 It uses the same frmat fr the maps (BSP), althugh with sme imprvements. Fr example, lighting is pre-calculated by using true radisity instead f the simplified algrithm that is used in the Quake engine. In additin, clred lights are supprted (even in mving bjects). Bth game engines have been released by Id Sftware under the GPL license, GLQuake in the 21 st f December f 1999, and Id Tech 2 engine in the 22 nd f December f This has lead t the creatin f numerus derived game engines fr several platfrms. Tw f the latest prts f these engines have been the versins fr the Symbian OS S60 platfrm, develped by Olli Hinkka. Nkia N95: The fllwing illustratin is a screenshts taken frm the Quake II engine running in a Illustratin 6. Screensht f Quake II running in a Nkia N95. Taken frm its dwnlad web page 2. Further infrmatin abut these engines can be fund in [13], [14], [15] and [16]. The main prblem with this engine is that it is quite difficult t wrk with it it has a mnlithic architecture- and that it is abslutely specialized in first persn shter games. In additin t that, it has many ther limitatins such as a lw number f supprted file frmats, a quite ld particle system, and s n. But it might be a very valuable example f hw t successfully prt a C applicatin t Symbian. 3.2 MOBILE 3D GRAPHICS APIS Once we have seen the available engines fr a mbile phne, and decided t develp ur wn, it is time t research abut the technlgies available fr ding s. A gd starting pint is t research abut graphics APIs. As it happens in persnal cmputers, 3D graphics APIs are used tday it was nt always like that, at first, there were nt standard APIs- in rder t get mbile phnes t render 3D graphics. 2 Page 26

27 The main design gals f that APIs are, accrding t [17]: Perfrmance. Being mbiles s resurce-cnstrained, perfrmance has t be kept in mind when designing fr them. In practice, this means minimizing the verhead that an applicatin wuld have t pay fr using a standard API instead f a prprietary slutin. Lw cmplexity. Bth the silicn area and the ROM memry are limited in mbile phnes. Because f that reasn, the APIs shuld be implementable in sftware with a reasnable ftprint. In rder t achieve this, remving redundant functinality is crucial. A rich feature set. Of curse, the API shuld be as cmplete as pssible. In general, thse functinalities that are hard t implement in the applicatin cde shuld be given by the API. Help keeping the applicatins small. Nt nly because f strage cnstraints, but als because distributin f mbile applicatins might be dne ver the air. Prviding cmmn functinality avid wasting space by prviding it in every applicatin. Hardware-friendly. The APIs shuld prvide a clear path fr hardware evlutin, s that graphics accelerating hardware can be built. Prductivity. The APIs shuld be as easy t use as pssible. Orthgnal feature set. This means that individual rendering features are nt tied t each ther. Feature rthgnality makes the behavir f the graphics engine easier t predict, as cmplex interdependencies and side-effects are minimized. This was already ne f the key design criteria fr OpenGL. Extensibility. The API shuld be prepared t evlve ver time, t avid being deprecated t early. Minimal fragmentatin. The API must avid having t many ptinal features, s that develpers have a gd set f features, which they can safely assume t be supprted by every device. Three APIs are available fr the time f writing: OpenGL ES, Direct3D Mbile and M3G. In the fllwing lines, they will be cvered briefly, just t highlight their histry a little bit and t remark their differences and particular features. An in-depth explanatin f mbile 3D graphics APIs, with in-depth explanatins f OpenGL ES and M3G, can be fund at [17]. It is a wnderful bk frm which a lt f the infrmatin presented in the fllwing lines has been extracted. As fr Direct3D Mbile, the best surce f infrmatin is the Micrsft Develper Netwrk r MSDN, which is surely familiar t anyne which has develped fr Windws any time-. The MSDN cntains an verwhelming amunt f infrmatin; hwever, it might be very difficult t find smething in particular. Because f this reasn, in the Direct3D Mbile sectin references t cncrete MSDN pages will be given. Page 27

28 3.2.1 OPENGL ES OpenGL ES -which stands fr OpenGL fr Embedded Systems- is an pen 3D graphics API fr created by the Khrns Grup. As its name suggests, it is based n the famus OpenGL API that is cmmnly used in persnal cmputers. OpenGL ES is crss-platfrm. Fr example, OpenGL ES 1.1 is available in Symbian OS and the iphne OS. There are als several sftware implementatins fr Windws Mbile. In the fllwing lines, we will intrduce this API by explaining its histry briefly and pinting ut a summary f the differences between the traditinal and embedded versin. Mre infrmatin can be fund in the fficial hme page f OpenGL ES APIs Brief OpenGL ES histry The first mbiles using 3D graphics appeared by the end f 2001 and the beginnings f The vendrs f thse mbiles slved the prblem f supprting 3D graphics in their wn way, ffering each f them different slutins fr essentially the same prblem. This is nt gd fr the market in the lng term. Develping 3D graphics fr each mbile phne wuld require different authring tls, making it very expensive. This is nt a gd scenari fr businesses t frm arund the market f 3D graphics fr mbile phnes. In 2002, the Khrns Grup, a standardizatin cnsrtium fr specifying and prmting mbile multimedia APIs, created a steering cmmittee fr defining a new ryalty-free API fr mbile 3D graphics. They chse OpenGL as their starting pint, and defined a set f design principles t which the new API must adhere. One f the gals was t keep the API as cmpact as pssible, in rder t enable sftware implementatins t be pssible with little cde (50kB f binary cde r less). In rder t achieve this, unnecessary functinality shuld be remved. The criteria fllwed was that mst variants f the same functin with several data types, functins that culd easily be emulated in applicatin cde if needed, and functins that were t resurce-expensive t be implemented in sftware culd be remved. Apart frm ding s, it was decided that backwards cmpatibility wuld nly be retained between minr versins (that is, 2.X is nt cmpatible with 1.X), which allws newer nes t have a fresh start. There are currently three main versins f OpenGL ES in the cmmn prfile we will talk abut prfiles later-: OpenGL 1.0, OpenGL 1.1 and OpenGL 2.0. The first tw versins have a fixed graphics pipeline, while OpenGL 2.0 uses a prgrammable 3D graphics pipeline with the ability t use vertex and fragment shaders in the OpenGL ES Shading Language. We will fcus n the 1.X versin frm nw n, as OpenGL 2.0 is currently nt supprted by any mbile phne althugh there are several GPUs fr mbile phnes that supprt OpenGL 2.0 already, see Graphics (page 70) fr mre details. 3 Page 28

29 Apart frm defining OpenGL ES, the Khrns grup is in charge f the fllwing APIs: OpenGL (as the OpenGL ARB was incrprated t the grup recently), COLLADA, glfx, OpenML, OpenVG, OpenMAX and OpenSL ES. Illustratin 7. OpenGL ES radmap Changes between OpenGL ES and OpenGL OpenGL ES is quite a big API, as OpenGL is. Because f that, the best way and the ne that interests us the mst-t express its multiple features, is just t cmment the differences between itself and the traditinal versin. are: The main differences between OpenGL ES 1.0 and OpenGL ES 1.3 n which it is based Numeric data types. Mst mbile phnes lack flating-pint units. Acknwledging this, OpenGL ES prvides supprt fr a new data type (GL_FIXED) which is, indeed, fr fixed-pint values. This shuld imprve perfrmance, especially when wrking with vertex data. In additin, duble is nt supprted by OpenGL ES, as it is nt recmmendable fr mbile phnes. Vertex data. In the OpenGL, it is pssible t prvide vertex data t the graphics pipeline by using states (the glbegin glend blcks that mst OpenGL develpers are familiar with) r by thrugh vertex arrays. As it is easier and mre efficient. Primitives. Triangles, lines and pints are supprted as lists, strips r fans. Hwever, Quads and plygns are nt supprted because they care really easy t Page 29

30 implement inside the applicatin if needed-. glplygnmde is nt supprted neither. Transfrming and lighting. The clr matrix stack n lnger exists in OpenGL ES. Texture crdinates generatin is als unsupprted as it can be dne by the applicatin itself-. In additin, nly RGBA clr mde is supprted. Cncerning lighting, there is neither supprt fr secndary clrs nr lcal viewer lighting mdel. Texturing. Only 2D texture mapping is supprted, as 1D is easy t emulate and 3D is t cstly in terms f resurces. There is n supprt fr cube mapping, texture brders, prxies, pririties, r LOD clamping. There is, hwever, supprt fr a new feature, called palette textures, which is a special and efficient- kind f cmpressed textures. Fragment pipeline. It remains unchanged but fr stencil buffering, which is ptinal. Frame buffer peratins. There is nly a single drawing buffer, and accumulatin is nt supprted. Sme 2D functins have been remved, and s have the functins required t reading back data frm the buffers. Miscellaneus. Evaluatrs, feedback, selectin and display lists have been mitted. They can be emulated by the applicatin itself, and anyway they are nt used ften. OpenGL 1.1 added sme new features (it is, indeed, based n OpenGL 1.5, in cntrast with OpenGL 1.0). Sme f them are: Vertex buffer bjects. These bjects allw string vertex data in the server side. Pint sprites. Pint sprites can be used fr 2D particle effects. User clip planes and matrix palette. Supprting at least ne user clip plane is required by the 1.1 specificatin. Texturing enhancements. Autmatic mipmap generatin is supprted, and s are texture cmbiners (which allw bumpmapping). Draw texture. An ptinal gldrawtextoes has been added, which is the same as the gldrawtext functin in OpenGL, but it allws caching. Dynamic state queries. 1.1 intrduces the ability t query back the OpenGL state. A cmprehensive list f all differences between OpenGL 1.5 and OpenGL Es 1.1 can be fund at [18]. Finally, the Extensin Pack we will talk abut what extensins in a few lines- add the fllwing ptinal features: Texturing enhancements. Texture crssbar, cube mapping and mirrred repeat mde supprt. New blending and stencil buffering mdes. Page 30

31 Frame buffer bjects supprt. A frame buffer bjects define a simple interface fr drawing t rendering destinatins ther than the buffers prvided t the GL by the windw-system. The cmplete specificatin fr the Extensin Pack can be lcated at [19]. As f tday, n device supprts the extensin pack at least nne that we knw f. Nevertheless, its extensins will be mandatry the will be indeed cre extensins- fr the OpenGL ES 1.2 API Prfiles The OpenGL specificatin defines nt nly a subset f OpenGL, but several, the s-called OpenGL ES prfiles. All the prfiles share the same rendering pipeline, namespace and cmmand structure. Hwever, each can have different cmmands, features and extensins. The current OpenGL ES specificatin has three prfiles, the cmmn prfile (CM), the cmmn-lite prfile (CL) and the Safety Critical prfile (SC): Cmmn Prfiles. It is intended fr cnsumer entertainment and related devices such as telephne handsets, PDAs, set-tp bxes, game cnsles, etc. There are tw cmmn prfiles: The Cmmn-Lite prfile. It requires less accuracy in calculatins and thus allws the implementatins t use fixed-pint numbers instead, althugh this is nt cmpulsry. The Cmmn prfile. It supprts bth fixed-pint and flating-pint arithmetic. The Safety Critical Prfile. It is intended fr cnsumer and industrial applicatins where reliability and certifiability are the primary cnstraints. It can be used in avinics and autmtive displays, fr example Extensin system Apart frm the cre functins, OpenGL ES as OpenGL des- has the pssibility f extensins. Extensins are functins that might be prvided by the cncrete vendrs t enhance OpenGL functinality. Successful extensins are gd candidates t be part f the cre functinality f further releases. Page 31

32 Utility APIs OpenGL lacks functins fr creating render targets such as windws r surfaces-. The way f ding it in the persnal cmputer envirnment is t use different libraries depending n the windwing system in use; fr example, GLX in X11, AGL in Mac, r WGL in Windws. OpenGL ES als lacks that functinality but, in rder t avid this fragmentatin, the Khrns grup created a crss-platfrm cmpanin API fr OpenGL ES called EGL. EGL unifies the OpenGL ES related resurce management acrss platfrms, and defines standard functin names, thus increasing surce level cmpatibility between platfrms. Other utility API that is famus in the persnal cmputer develpment is GLUT, the GL Utility Tlkit. It prvides system-level I/O and prvides rutines fr drawing sme gemetric primitives. When the library became unmaintained, a new implementatin f the library, rebuilt frm scratch was created, freeglut this was needed because the license f GLUT frbade the redistributin f mdified versins-. Later n, a new API appeared, based n freeglut and extending it, OpenGLUT. There are n versins f thse libraries fr mbile phnes but in the case f freeglut, which has been prted fr the Windws CE, in a library called GLUT ES. Mre infrmatin n these libraries can be fund at GLUT 4, FreeGLUT 5, OpenGLUT 6, and GLUT ES 7 web pages MOBILE 3D GRAPHICS API (M3G) Mbile 3D graphics API (als called M3G) is an API that prvides 3D graphics supprt fr the Java ME platfrm. It was prpsed by Nkia t the Java Cmmunity Prcess and it is part f the Mbile Service Architecture since M3G is supprted in Symbian OS. Windws Mbile des nt supprt M3G, as it lacks supprt fr Java ME ut-f-the-bx -althugh it can be installed via the PhneME prject. Please, see [20] fr mre details) Brief M3G histry The first mbiles with supprt fr the Java ME platfrm -Java Micr Editin- appeared in Smetime later, games begin t appear fr Java ME. Hwever, the market was abslutely fragmented, as each cmpany develped their wn sftware renderers. Being games ne f the mst attractive applicatins fr mbile phnes at the mment, sme cmpanies began t want a specifics API fr games and 3D graphics in Java ME. In rder t d s, the Java ME platfrm wuld need t be added new cmpnents, thus requiring new specificatins. Requests fr mdificatin r additins f specificatins fr the Java ME platfrm are dne via requests t the JCP -Java Cmmunity Prcess-. The slicitr has t fill a request Page 32

33 called Java Specificatin Request, r JSR. Then, there is a reviewing perid in which anyne can make cmments abut the JSR. During that perid, the Executive Cmmittee fr ME has t vte in favr r against the JSR. Shuld the results be favrable, the JSR cntinues by creating an early draft f the specificatin and s n; therwise, the reslutin can be requested t be recnsidered. The illustratin belw shws a typical timeline f the prcess; fr a full detailed explanatin, please refer t [21]. Illustratin 8. JCP timeline. The first JSR Java Specificatin Requests- aimed t bring games fr the Java ME platfrm was the JSR-178: Mbile Game API, which was submitted in March 2002 by In-Fusi. Just a mnth later, Nkia submitted the JSR-184: Mbile 3D Graphics API fr J2ME TM. The JSR-178 was rejected with 6 vtes in favr and 9 against. The JSR-184, hwever, was apprved with 12 vtes in favr and nly 1 against. The main difference between bth JSRs relays n their gal: while JSR-178 was specific fr games, JSR-184 is fr 3D graphics in general, allwing ther applicatins. The JSR-184 had its first final release in 22 Dec, 2003, and was updated in 24 August, This is ften called as the M3G 1.1. A new versin f the API has been prpsed in the JSR-297: Mbile 3D Graphics API 2.0. It has been accepted with 11 vtes in favr and 2 vtes against. Its public review perid is due t finish in September f This new versin is meant t supprt prgrammable shaders and t imprve perfrmance even in devices with a fixed pipeline. As it is Anther related JSR is JSR-239: Java TM Binding fr the OpenGL ES API. It was submitted by Sun Micrsystems in February, 2004 and apprved with 14 vtes in favr and nne against. The final release f the specificatin was published in September This API nt widely supprted, hwever, being Sny-Ericcsn the nly manufacturer ding s by this time. In December 2006, the JSR-184 became part f the Mbile Service Architecture specificatin (JSR 248: Mbile Service Architecture) which ffers a reference set f JSR that shuld be implemented in every Java ME platfrm. Page 33

34 All the JSR dcuments can be fund in the web page f the Java Cmmunity Prcess, which can be lcated at the JCP web page API verview M3G we will nly refer t M3G 1.1, as M3G 2.0 is still in a very early stage- uses a rendering pipeline very similar t OpenGL ES. In fact, it is pssible t use OpenGL ES fr as the lwer layer f the API implementatin althugh it is still pssible t use sftware renderers. Having OpenGL ES as the lwer layer als implies that hardware acceleratin is supprted-. Illustratin 9. M3G transfrming and lightning pipeline. Illustratin taken frm [17]. Mst f the features f OpenGL ES 1.0 are available thrugh M3G, althugh few have been simplified (fr example, blending and depth testing) and thers have been kept ut f 8 Page 34

35 the API (that is the case f pints, lines, anything that is ptinal in OpenGL ES, r sme ther features such as stencil buffering). The M3G library can be used in tw mdes. Immediate mde and retained mde. In immediate mde it wrks the same way as OpenGL des: the applicatin executes a functin f the API, which in turn sends a cmmand t the render pipeline, which immediately perfrms an peratin. This has prblems in terms f perfrmance. Java ME is nt a native language; it is cmpiled int bytecde nt machine cde- and then executed/interpreted in a Java Virtual Machine. This prcess is slw cmpared t native cde executin; indeed, it might be slw enugh nt t be able t keep the rendering pipeline busy, which means wasting the per-se limited graphic pwer f the device. T vercme this prblem, the retained mde was created. In this mde, an entire scene graph is defined and nly minr changes have t be dne t it in per-frame basis. This way, mst f the amunt f Java cde executed is reduced t a minimum, thus greatly reducing the verhead f the virtual machine. In sme cases, the best apprach is t render mst f the scene in retained mde, adding perhaps a player character and sme special effects int the scene using the immediate mde. Additinal features f M3G include extensive supprt fr animatin and binary cntent files. Any prperty f any bject can be keyframe-animated, and there are special types f meshes that supprt skinning (bne-based animatin) and mrphing (animatin by linear interplatin). There is als an assciated standardized binary file frmat assciated with the M3G API Perfrmance cmparisn between OpenGL ES and M3G In rder t cmpare the perfrmance between a native applicatin using OpenGL ES, and a Java ME applicatin using M3G, tw benchmarks frm Kishnti Infrmatics can be used: JBenchmark HD 9 and GLBenchmark HD 10. Bth benchmarks use the same scenes fr their tests, s there are ideal fr the cmparisn between APIs. The fllwing is a table cmparing the results btained by different mbile phnes f different manufacturers in the tw benchmarks. 9 Available at 10 Available at Page 35

36 Device name JBenchmark GLBenchmark Rati J/GL JB samples GL samples Nkia N ,49% Nkia N95 8GB ,94% Nkia N ,74% Nkia E ,18% Nkia N93i ,19% 5 13 SnyEricssn ,77% 1 39 W950i Dell Axim X51v ,27% 1 47 HTC P ,62% 7 18 TyTN II (Kaiser) LG KS ,69% 2 5 Table 1. Perfrmance cmparisn between OpenGL ES and M3G. The results are specified in frames shwed fr a fixed amunt f time. The last tw clumns refers t the number f results frm which the JBenchmark and GLBenchmark values were averaged. It can be seen that using OpenGL ES is at least twice as fast as using M3G. It wuld be useful t knw hw much the JBenchmark uses the immediate and retained mdes, as it has a direct impact in perfrmance, but that infrmatin is nt available DIRECT3D MOBILE Direct3D Mbile is the versin f Direct3D fr Windws Mbile and Windws CE. Amng its strng pints is the fact that it is bject riented such as M3G- but native such as OpenGL-. Disgracefully, it is a clse API nly available in the tw already-mentined Micrsft perating systems. The main surce f infrmatin cncerning Direct3D Mbile is its MSDN entry Brief Histry f Direct3D Mbile When the first versins f Windws CE the precursr f Windws Mbile, as can be read in Brief histry f Windws Mbile (page 54)- were released, handheld devices were really limited in term f hardware (they had n graphics acceleratin, very slw CPUs and small memries, nt gd sund synthesizers, etc). Because f this reasn, develpers f Windws CE didn t prt the DirectX libraries t their perating system fr Pcket PCs. This was a prblem t thse that wanted t create games fr Pcket PCs even simple enugh t vercme thse hardware limitatins-. A fast actin game needs fast screen updates. The nly way t achieve this was t have direct access t the screen memry but. Disgracefully, this needed t be dne in a different ways fr different hardware, which made this very difficult and tedius. In rder t slve this prblem, Micrsft added the GAPI which stands fr Game API- t Pcket PC 2000 in April This API prvides, amng ther things, device-independent 11 Page 36

37 methds fr accessing the screen memry, thus easing the develpment f games fr Pcket PCs. Just fr the sake f curisity, it must be said that there already existed a versin f DirectX fr Windws CE, but nly fr a versin f the perating system that can be used within games f the Dreamcast cnsle (such as Sega Rally 2). As GAPI writes directly t the screen memry, it cannt take advantage f hardware acceleratin. Because f this reasn, a prt f the Direct3D library (part f the DirectX suite) was dne fr Windws CE 5.0, the s-called Direct3D Mbile. Windws Mbile 5.0 and later n Windws Mbile 6.X als supprt Direct3D. Obviusly, the usage f Direct3D is preferred ver the GAPI library, which is nly supprted fr legacy sftware and fr its input management functins, whse usage is still advisable. This infrmatin has been cmpiled frm [22], and [23] Changes between Direct3D and Direct3D Mbile Direct3D Mbile is based n Direct3D 8, althugh it supprts sme functins f Direct3D 9. The features f the PC versins that are nt supprted in Direct3D Mbile, accrding t [24] are: Bump mapping Cube maps Edge antialiasing Emissive materials Gamma crrectin Higher-rder primitives Line stippling Mirrr-nce texture wrapping Multisample masking Nn-lcal vide memry Phng shading Pixel shaders Pint sprites Spt lights State blcks Sterescpic viewing Switching between hardware-based and sftware-based vertex prcessing mdes User clip planes Vertex blending and indexed vertex blending Vertex shaders Vlume r vlume textures As it can be seen, Direct3DMbile has n supprt fr shaders; it has a fixed pipeline. Just t be able t cmpare, the features written in italics are thse that are supprted in OpenGL Page 37

38 1.1. -There are als features f Direct 3D Mbile nt supprted by OpenGL ES, such as multiple back buffers, but they are far less imprtant-. There are ther features that are nly partially supprted. Fr example, Direct3D Mbile nly supprts the HAL device by default althugh sftware devices can be used after they are registered with a functin call-. Other imprtant limitatin is that nly a single device can be instantiated at any ne time. This means that nly ne applicatin using Direct3D Mbile can be executed at a time i.e. if there an applicatin using Direct3D Mbile in the backgrund, a new applicatin that uses Direct3d Mbile cannt be started-. Apart frm the differences in terms f features, it is als imprtant fr a develper t knw that mst structures, names and interfaces have been renamed with respect t Direct3D 8. This shuld nt be a prblem, hwever, as they keep a ne-t-ne mapping. Finally, Direct3D adds supprt fr fixed pint values in frmat Direct3D Mbile Extensins As there is a Mbile versin f Direct3D, there is als a Mbile versin f the Direct3D Extensins (D3DX) library. This library includes: sme helper functins fr matrices and vectrs (fr bth flating pint and fixed pint data types) and texture management; macrs fr data type cnversins; and structures t hld matrices and vectrs. A cmplete reference f this library can be fund at [25]. 3.3 MOBILE OPERATING SYSTEMS / SOFTWARE PLATFORMS The mbile envirnment is very hetergeneus in terms f perating systems and sftware platfrms. What fllws is a study f the mst relevant perating systems and sftware platfrms fr mbile devices that can be fund tday, taking int accunt what ur gal is. Only tw perating systems have resulted suitable fr ur purpses, Symbian OS and Windws Mbile, and s they are explained in greater detail than the ther perating systems. Fr thse perating systems that were discarded as pssible targets nly a very brief descriptin and the reasns why they were discarded are given. Hwever, fr Symbian OS and Windws Mbile, their histry, features, prgramming languages and security mdels are explained in detail, as they are imprtant aspects t be taken int accunt. After these explanatins, a brief market study is shwn, as it is imprtant t take int accunt which perating systems are the mst used: the mre spread an perating system is, the mre users an applicatin built fr it can reach SYMBIAN OS Symbian OS is an perating system develped and licensed by Symbian Ltd. Its current versin is the 9.5, althugh the latest versin that can be fund in an actual device is the 9.2. Page 38

39 In the fllwing sectins, several aspects f the perating system will be cmmented, such as its histry, its main features, in which languages applicatins can be develped fr it and ther imprtant facts abut the system Brief histry f Symbian The histry f Symbian begins far befre it was called by that name. In 1994, Psin was a cmpany that manufactured PDAs (the mst recent was the Psin Series 3). Their perating system was als develped by Psin; it was a 16-bit OS named SIBO. Neither had Palm released Pilt nr had Micrsft released Windws CE yet, and Apple s Newtn had nt been a success. The nly cmpeting cmpany was Hewlett-Packard, which were primitive in cmparisn (being their OS DOS-based). The next prject f Psin was t replace SIBO by a new, 32-bit perating system, which was cdenamed Prtea and later named EPOC. This new system was being designed frm scratch and by peple with lng-term visin. By 1997, EPOC OS was released. Al mst a year later, the sftware divisin f Psin spun ff. When this happened, there were several strategies they culd have fllwed, but finally they decided t make sftware licensing their business. Nkia came t Psin Sftware fr the first time because they were lking fr an perating system fr their Cmmunicatr mbile, and they were interested in the Prtea prject. By that time, the first Windws PcketPC and the Palm Pilts were already in the market, and Nkia and ther manufacturers were wrried abut their psitin in the market specially, they was wrried abut the pssibility f Micrsft cping all the market, as it had happened in the PC wrld-. Because f that, Nkia led the creatin f a cnsrtium that included Siemens, Mtrla, Ericssn, Psin, Panasnic and Samsung, which in 24 th f June, 1998 resulted in Symbian. The Symbian OS evlved frm the EPOC 2 OS, in what can be cnsidered the Symbian OS 5 althugh it was never called this way. Its architecture was built based n three main rules: User data is sacred User time is precius All resurces are scarce This led t several design principles that have been maintained since their cnceptin, in spite f the cnstant evlutin f the perating system. The first versin that was develped t be used in mbile phnes (smartphnes) was the 5 th versin althugh it was never called like that-. The next versin, cdenamed ER5u, included full Unicde supprt and, finally, the first versin f Symbian that hit the market was the sixth. An entire chapter devted t the histry f Symbian can be fund in [26]. Page 39

40 Illustratin 10. Symbian OS 9.2 architecture. The cmpnents f the Symbian OS are shwn in range Features As f tday (June 2008), the last stable versin f Symbian OS is the 9.5, althugh the newest phnes include just the 9.2 versin. A full list f the features f the 9.2 versin can be fund in [27], being the mst relevant nes fr us the fllwing. Supprt fr different user interfaces. Such as Series 60 r UIQ (we will talk abut them in the next sectin). Platfrm security system. The access t different features f the perating system is limited via a capability system (abut which we will talk later, t). Cmprehensive Java supprt. Supprts the latest wireless Java standards, including CLDC 1.1, MIDP 2.0, JTWI (JSR185), Mbile Media API (JSR135), Bluetth (JSR082), Wireless Messaging (JSR120), Mbile 3D Graphics API (JSR184), Persnal Infrmatin Management and FileGCF APIs (JSR075) and Cntent Handling API (JSR 211) Hard real-time capabilities. A real-time, multithreaded kernel prvides the basis fr a rbust, pwer-efficient and respnsive phne and enables supprt fr a single-cre architecture. Supprt fr the latest hardware. Supprts the latest CPU architectures, peripherals and internal and external memry types. Rich multimedia capabilities. Audi and vide supprt fr recrding, playback and streaming; image cnversin Pwerful graphics. Direct access t screen and keybard fr high perfrmance; graphics acceleratr API (by the means f the OpenGL ES API); increased UI flexibility (supprt fr multiple simultaneus display, multiple display sizes and multiple display rientatin). Page 40

41 Brad supprt fr cmmunicatins prtcls. Wide area netwrking stacks including TCP/IP (dual mde IPv4/v6), RTP, RTCP and SIP, and WAP 2.0 (Cnnectinless WSP and WAP Push); persnal area netwrking supprt including infrared (IrDA), Bluetth and USB; supprt fr multi-hming and link layer Quality-f-Service (QS) n GPRS and UMTS netwrks; supprt is als included fr bearer mbility Rich set f ptins fr develping fr Symbian OS. Cntent develpment ptins include: C++, Java (J2ME) MIDP 2.0 and WAP; tls are available fr building C++ and Java applicatins; reference telephny abstractin layer fr 2G, 2.5G and 3G prvided. Versins 9.3, 9.4 and 9.5 add imprved memry management, native Wi-Fi supprt, SQL Lite and ther new features. All this versins are backwards cmpatible, unlike the 9.0 versins, which brke cmpatibility with previus versins. It is als remarkable that Symbian Ltd has annunced its intentins f buying the entire Symbian Ltd and create the Symbian Fundatin, that wuld make Symbian OS pen-surce by 2010 (see the press release at [28]). Up f tday, Symbian has been used in a ttal f 129 phnes, accrding t [29] User Interfaces / Platfrms In rder t ffer the maximum flexibility, Symbian OS deliberately lacks a User Interface layer (althugh it ffers an UI framewrk s that it is easier t create a UI, as seen in the Illustratin 10). Because f this reasn, Symbian OS cannt simply be used as is by its licensrs, but they have t prvide their wn User Interface t be used n tp f the OS. There is, therefre, a need t extend the perating system t prvide a user interface. Hwever, there is n reasn why nt ther features culd be added. The Series 60 platfrm, fr example, ffers nt nly a user interface but als new features that are nt in the cre Symbian OS (in fact, S60 is said t have twice the cde f Symbian, as can be read in [26]). We will see abut this in the next lines. Each platfrm ffers als its wn develpment tls that expse the specific features f the platfrm t the develpers. The mst imprtant UI/platfrms fr Symbian OS are S60, develped by Nkia; UIQ, develped by UIQ Technlgy; and MOAP, develped NTT DCM fr its FOMA service. There are thers, such as S80 r 7110 frmerly S60, bth develped by Nkia- that are present nly in a few devices and are nt expected t appear in new mbile phne, due t which they are nt cnsidered fr new develpments Series 60 platfrm Series 60, r S60 as it is als called, is a platfrm develped by Nkia Mbile Sftware. The S60 platfrm guarantees t develpers that specific elements will be presented in every device using a particular versin and feature pack. Page 41

42 There have been 9 versins f the platfrm, frm the S60 1 st editin t the current S60 3 rd editin FP2 althugh there are still n devices using the last versin, being the 3 rd FP 1 the ne shipped nwadays-. The fllwing illustratin shws the cmpatibility issues between them. Mre in-depth infrmatin abut the differences between the 3 rd and 2 nd editins can be fund at [30]. Illustratin 11. S60 cmpatibility between versins. Nte that there were als an FP1 fr the 1 st editin that fr unknwn reasns has nt been drawn in the illustratin. Taken frm [30]. It is imprtant t recall that nt nly Nkia uses the S60 platfrm, but als Panasnic, Samsung, Siemens LG and Lenv. A full, updated list f devices using S60 can be fund at the S60 devices database 12. As f tday, 73 mbile phnes using S60 have been released, frm which 47 use the 3 rd Editin. The S60 platfrm adds many features t the Symbian OS. The fllwing illustratin shws the architecture f the platfrm, and afterwards, each cmpnent is explained briefly. A mre cmplete verview f the S60 platfrm can be fund in [31]. 12 Page 42

43 Illustratin 12. Architecture f the S60 platfrm. The elements prvided with the S60 are brdered. Taken frm [31]. The different cmpnents are, frm bttm t tp: Symbian OS Extensins: Features that are added t the Symbian OS cre features, such as functins t manage vibratin, device lights, battery charge status, r even mre advanced things such as WLAN r Assisted GPS supprt. Open C: In rder t make migrating PC applicatins t the S60 platfrm easier, since the S60 3 rd editin FP1 a subset f the POSIX (Prtable Operating System Interface) libraries is included thrugh Open C. We will talk abut them later in the sectin Migratin pssibilities later). S60 Platfrm Services: These are the fundamental services prvided by the S60 platfrm. They are the Applicatin Framewrk Services, the UI Framewrk Services, the Graphics Services, the Lcatin Services, the Web-Bases Services, the Multimedia Services and the Cmmunicatin Services. S60 Applicatin Services: They prvide certain basic functinality t the applicatins, such as PIM Applicatin Services (where PIM stands fr Persnal Infrmatin Management), Messaging Applicatin Services and Brwser Applicatin Services. S60 Java TM Technlgy Services: Prvide supprt fr Java applicatin, including several APIs t allw Java applicatins t access t mst f the S60 platfrm features. Web Run-Time: It was intrduced in the Feature Pack 2 f the S60 3 rd Editin (althugh sme FP1 devices can be updated t include it). WRT is a runtime envirnment that allws the installatin and use f Web Widgets in the devices. It is wrth mentining that, althugh S60 3 rd editin des nt supprt tuch screens, Nkia is develping and researching in what they call the S60 Tuch platfrm, which is said t present the fllwing features (frm [32]): Page 43

44 Supprt fr bth fingers and stylus input Supprt fr tactile feedback (haptic technlgy) Backward cmpatibility with S60 3 rd editin (which is als prmised by Nkia, as can be seen in the Illustratin 11). The first results f that research will be seen in the upcming Series 60 5 th Editin, which will be first incrprated in the Nkia 5800 Xpress Music. Mre infrmatin abut it can be fund in [33]. In rder t develp fr S60, a S60 SDK is required (which can be dwnladed fr free). The SDK can wrk with several IDEs, such as Carbide.c++ r Visual Studi with the Carbide.vs plug-ins. There are free versins available f all f them that are suitable fr the purpse f develping fr S60. The SDK allw the creatin f OpenGL ES 1.1 applicatins since the versin 2 nd Ed. FP2. Mre infrmatin abut develping fr the S60 platfrm can be fund at [34] UIQ platfrm UIQ (which stands fr User Interface Quartz) is an pen platfrm it is said t be pen because it can be extended by installing new applicatins n tp f it- develped by UIQ Technlgy AB. UIQ is defined by UIQ as a user interface and a develpment platfrm. One f the main characteristics f the UIQ platfrm is its supprt fr tuch screens, which S60 lacks as f nw. There have been eight versins f the UIQ platfrm: UIQ 1.0 (released in 2000), UIQ 1.1 (2001), UIQ 2.0 (2002), UIQ 2.1 (2003), UIQ 3.0 (2005), UIQ 3.1 (2007), UIQ 3.2 (2008) and the newest ne: UIQ 3.3 (2008). Hwever, there are still n devices using this last versin, being the UIQ 3.2 versin the newest used in a real device. Similarly t what happened with the S60 platfrm, the versin 3 brke the cmpatibility with previus versins (in fact, it was Symbian OS 9.0 wh brke it in bth cases). A ttal f 20 mbile phnes have been released that use the UIQ platfrm. There have been 11 phnes running the UIQ 2 versin released by Sny Ericssn, Mtrla, BenQ and Arima; and anther 9 running the UIQ 3 versin, released by Sny Ericssn and Mtrla. The UIQ architecture can be seen in the fllwing illustratin: Page 44

45 Illustratin 13. The UIQ platfrm architecture. The develpment platfrm cntains a set f cmpnents and APIs that can be used by develpers t create new applicatins. These cmpnents are: Applicatin framewrk: Defines the main structures and UI behavirs needed by new applicatins. System services: Offers sme UIQ specific services than can be used by every applicatin. Rich GUI tlkit: UI cntrls that applicatins can use t build its graphical user interfaces. J2ME (Java): Set f Java APIs s that Java applicatins can run in the phne. A much mre in-depth explanatin f UIQ and all its releases can be fund at [35]. Cncerning the develpment tls, the UIQ SDK is required (which can be dwnladed fr free nly by registered develpers, which is nt a prblem since signing up is als free). Sme extensins can be dwnladed fr specific phnes. The SDK is cmpatible with the fllwing IDEs: Carbide.c++, Visual Studi with Carbide.vs, MOTODEV Studi fr UIQ and VistaMax. There are free versins f all f them except f VistaMax. The SDK allw the creatin f OpenGL ES 1.1 applicatins via several Sny Ericssn extensins. Mre infrmatin abut develping fr UIQ can be fund at [36] MOAP platfrm MOAP, which stands fr Mbile Oriented Applicatin Platfrm, is a platfrm develped by NTT DCM, the predminant mbile peratr f Japan. Page 45

46 MOAP is nt an pen platfrm, s it is nt pssible fr third parties t develp applicatins fr it. Because f this reasn, there is nt much technical infrmatin available abut it, and anyway it wuld be f n use fr us. The reasn why the MOAP platfrm is imprtant is because there have been 59 mbile phnes released that uses it (accrding t [29]), which is apprximately the 45% f all the phnes that use Symbian OS Platfrm Security: Symbian Signed Prgram A malicius applicatin within a mbile phne culd perfrm critical peratins such as making phne calls r transmit data ver GPRS (being bth peratins critical, as they cst mney t the phne user), r even access critical infrmatin such as telephne numbers, addresses, etc. withut ntifying the user. In rder t prtect the user frm these applicatins, Symbian OS uses have a very strng platfrm security system, whse main elements are the s-called capabilities. Sme f the functins ffered by the System OS APIs are capability-prtected (this is what Symbian calls Firewall prtectin, r Capability-based access cntrl) which is called, which means that nly applicatin that have been granted a certain set f capabilities can call them. Fr example, an applicatin that needs t make phne calls needs t have a specific t d s. Capabilities are als used t ensure that applicatins des nt access parts f the file system that might cntain sensitive data fr the user r that culd damage the phne (this is what Symbian calls data caging). T use a capability, an applicatin needs t declare it at build time and, then, it needs t be granted permissins t use it. This can be dne when the applicatin is signed, r after asking the user at runtime (being given what are called single-sht permissins) Page 46

47 Capability Type Capability Name Descriptin Availability User Capabilities LcalServices Lcatin NetwrkServices ReadUserData UserEnvirnment WriteUserData User Capabilities are designed t be meaningful t mbile phne users Depending n Device Manufacturer security plicies, users may be able t grant blanket r single-sht permissins t applicatins which use these Capabilities All signing ptins System Capabilities Restricted Capabilities Device Manufacturer Capabilities PwerMgmt PrtServ ReadDeviceData SurrundingsDD SwEvent TrustedUI WriteDeviceData CmmDD DiskAdmin NetwrkCntrl MultimediaDD AllFiles DRM TCB Table 2. Symbian OS Capabilities. Taken frm [37]. System Capabilities that prtect system services, device settings, and sme hardware features Restricted Capabilities that prtect file system, cmmunicatins, and multimedia device services Trusted Cmputing Base and System Capabilities that prtect the mst sensitive system services All signing ptins Open Signed (with Publisher ID) and Certified Signed ptins nly Require Device Manufacturer apprval In rder t be installable in Symbian 9.x an applicatin must have been signed (prir versins culd run unsigned applicatins). There are tw ways f signing an applicatin: selfsigning it (that is, the develper creates its wn certificate and uses it t signs its applicatin) r signing it thrugh the Symbian Signed Prgram. The prgram ffers several ptins at a different price depending n the develper needs. Nt all ptins allw the signed applicatin t have all the available capacities, and they can even impse IMEI restrictins -IMEI stands fr Internatinal Mbile Equipment Identity is a unique id that identifies a mbile phne-. Self-signed applicatins can nly psses User Capabilities (see Table 2), and are nt cnsidered as trusted by the device. Because f this, a warning is issued whenever a selfsigned applicatin is installed. On the ther side, the Symbian Signed prgram ffers the fllwing ptins: Page 47

48 Signing Optin Publisher ID required Independent Testing Required IMEI Restrictins Open Signed N N Yes (1) N Online Open Signed Yes N Yes (1000 max) N ffline Express Signed Yes N N Yes Certified Yes Yes N Yes Signed Table 3. Signing ptins in the Symbian Signed Prgram. Taken frm [37]. Fr Cmmercial Distributin? Requiring a publisher ID is quite cstly ($200.00, VAT exclusive, fr ne year), especially fr hbbyist r develpers f free applicatins. Because f this, Symbian created the nline Open Signed ptin. It is abslutely free, ffers access t bth User and System capabilities, and signed applicatins are valid fr 36 mnths. In rder t develp a graphics engine, neither Restricted nr Device Manufacturer Capabilities shuld be needed, s the Security Platfrm f the Symbian OS shuld nt be a prblem. Java applicatins are nt required t pass thrugh the Symbian Signed prgram, as they have their wn security mdel (the MIDP 2.0 security mdel. An in-depth explanatin fr it can be fund at [38]. Mre infrmatin abut the Symbian Signed Prgram can be lcated at [37] Prgramming languages The prgramming languages in which new applicatins can be develped fr Symbian OS depend n the SDK f the platfrm targeted by these applicatins. Hwever, bth S60 and UIQ allw the develper t use almst the same languages: Symbian C++, Java, and Pythn. Widgets can be develped fr S60 3 rd Editin FP2 (and sme FP1) and UIQ 3.3. Flash Lite is nly available fr the S60 platfrm Symbian OS C++ Symbian OS C++ is the native language f the Symbian OS, which means that applicatins created using it are nt interpreted but cmpiled. Symbian OS C++ was created befre ANSI standardized C++ in 1998, and hence there are several differences between Symbian OS C++ and ANSI C++. Mst f them are related t inheritance rules, strings, exceptin handling, etc. Symbian OS C++ ffers als sme extensins t the ANSI versin, such as lightweight exceptins and memry management utilities. A cmprehensive list f differences between ANSI C++ and Symbian OS C++ can be fund at [39]. Als, [40] is a great bk devted t Symbian OS C++. Page 48

49 Frtunately, the syntax is similar in bth languages, and the differences shuld be fairly easy t vercme. Fr example, naming cnventins differences can be easily slved by using typedefs, and Symbian OS C++ extensins are nt required t be used at all Java Anther ptin is t use Java (in its Mbile Editin) fr develp fr Symbian. Java applicatins are then cmpiled t bytecde, which is later interpreted by the Java Virtual Machine. The Java APIs available t the prgrammer depend n the platfrm targeted. Infrmatin abut which APIs are supprted in the S60 platfrm can be fund at [41], while the APIs supprted by UIQ3 can be fund at [42]. Bth platfrms, hwever, supprt the Mbile 3D API fr Java ME (JSR-184). A cmparisn between Java and C++ develpment can be read in [43]. Basically, it is easier t develp Java applicatins, but they are slwer and have access t fewer features. Especially relevant fr us is the benchmark included in the fifth sectin f that dcument. The perfrmance f a game develped in J2ME and the same game develped in native C++ is cmpared. The cnclusin reached by Ideawrks3D (develpers f the Airplay Engine, as sw in the sectin Explred search results) is that nly C++ applicatins can reach cnsle-level perfrmance when it cmes t 3D games due t the pr rendering ptins f J2ME Pythn Pythn is a scripting language that is partially supprted by bth the S60 and UIQ via different interpreters. S60 uses PyS60 13, whereas UIQ3 uses PyUIQ 14. In fact, the UIQ3 versin is a patched versin f the PyS60. Frm their respective pages, dcumentatin abut bth implementatins can be dwnladed. As PyUIQ is based n PyS60, they bth supprt the same APIs (althugh the last available versin f PyUIQ might nt be based n the last available versin f PyS60). They bth have OpenGL ES bindings, s it is pssible t use OpenGL Es frm within Pythn scripts. Unfrtunately, Pythn is ne f the slwest prgramming languages, s its usage fr real-time applicatins is highly discuraged Flash Lite Flash Lite is nly available in the S60 platfrm. It is the lightweight versin f the Adbe Flash technlgy. Due t its pr graphics perfrmance (as it supprts nly vectr graphics) and its API limitatins, it is nt well suited fr cmplex applicatins such as the ne we aim t develp Page 49

50 Widget Widgets are small single-purpse applicatins built using standard technlgies such as JavaScript, AJAX, HTML, CSS, etc. They are bviusly nt suitable fr creating a graphics engine, but they are interesting because there are really trendy, nwadays. Widgets are supprted in many perating systems (frm bth desktp and mbile envirnments) and there is even a W3C recmmendatin fr their standardizatin (which can be accessed at [44]) Migratin pssibilities There are several libraries that can be used t ease the prcess f prting an applicatin frm the PC t Symbian OS: P.I.P.S, Open C/C++, ustl and STL. The first tw nes aim t prvide POSIX supprt t the Symbian OS, while the tw last are implementatins f the STL (Standard Template Library) that can be used n Symbian OS. Since P.I.P.S lacks an STL implementatin (and Open C lacked it until very recently) they are quite interesting in fact, ustl might be even preferred ver the Open C/C++ implementatin-. Nte that althugh Windws prvides a POSIX layer, it is almst never used by Windws applicatins. Because f this reasn, prting Windws applicatins t Symbian OS might require an almst cmplete rewrk. Prting frm Linux, hwever, wuld be much easier thanks t these libraries P.I.P.S. P.I.P.S. stands fr P.I.P.S. Is POSIX n Symbian OS a recursive acrnym. The Symbian OS was nt designed t be POSIX cmpatible as it had ther mre imprtant design gals such as running in devices as cnstrained in resurces as mbile phnes are. POSIX (which stands fr Prtable Operating System Interface, which an extra X fr UNIX), is a standard aimed t ensure that applicatins created fr a standard-cmpliant OS culd als be cmpiled in anther standard-cmpliant OS. Thus, making Symbian OS POSIX cmpatible (r mstly) wuld ease the migratin f applicatins frm ther POSIX-cmpliant r mstly cmpliant- perating systems (such as Mac OS X r Linux) t Symbian OS. Symbian Ltd started the P.I.P.S. initiative in January f 2007, aimed t extends Symbian OS t make it as POSIX-cmpatible as pssible. By the same time, Nkia was thinking abut ding the same fr its Nkia S60 platfrm, s they bth jining effrts resulting in tw different sets f libraries, P.I.P.S. and Open C (Open C is a superset f P.I.P.S. fr the S60 platfrm). P.I.P.S. prvides the fllwing libraries: libc: Standard C and POSIX APIs - includes supprt fr files, sckets, pipes, message queues, shared memry APIs and envirnment variables libm: Standard C math supprt APIs Page 50

51 libpthread: Standard POSIX threading APIs libdl: Standard C dynamic lading and symbl lkup APIs (nly rdinal lkup is supprted n pre-symbian OS v9.3 releases). In rder t use P.I.P.S, it is necessary t update the SDK f the platfrm targeted t include the new libraries, and t install the P.I.P.S shared library in thse devices in which the develped applicatins are ging t be used. This will nt be necessary in mbiles running Symbian OS 9.5 r beynd, as P.I.P.S. will be included in the cre f the OS. The current versin f P.I.P.S. as f tday is the 1.3, released in May 27, Frm Symbian OS 9.5, P.I.P.S. will be included in the cre f the OS. The fficial webpage fr P.I.P.S, frm which bth the binaries and the dcumentatin can be dwnladed frm its dwnlad page Open C/C++ As said, Open C was created as a superset f P.I.P.S. develped by Nkia fr its S60 platfrm. It is based n P.I.P.S. and updated at the same time. Hwever, in June 2008, Open C evlved t Open C/C++, as new C++ libraries were added. Open C/C++ adds supprt fr the fllwing libraries: Open C Library Descriptin Surce Functin cverage (%)* libc A set f Standard C libraries prviding standard FreeBSD 47 input/utput rutines, database rutines, bit peratrs, string peratrs, character tests and character peratrs, DES encryptin rutines, strage allcatin, time functins, and signal handling. libpthread IEEE Std c (POSIX) is the standard interface fr FreeBSD 60 implementing multiple threads f executin within a traditinal user prcess. The library includes APIs fr thread creatin and destructin, an interface t the thread scheduler t establish thread-scheduling parameters, and mutex and cnditin variables t prvide mechanisms fr the prgrammer t synchrnize access t shared prcess resurces. libm Arithmetical and mathematical functins that perate FreeBSD 42 accrding t the Standard C library. libdl This library prvides APIs that lad DLLs. FreeBSD 100 libz The zlib cmpressin library prvides in-memry zlib 100 cmpressin and decmpressin functins, including integrity checks f the uncmpressed data. libcrypt Cryptgraphy libraries that cntain functins fr encrypting blcks f data, messages, and passwrd OpenSSL Page 51

52 libcrypt libglib libssl IOStreams STL Bst hashing. This library prvides services that are used by the OpenSSL implementatins f SSL, TLS, and S/MIME, and have als been used t implement SSH, OpenPGP, and ther cryptgraphic standards. This general-purpse utility library prvides, fr example, many useful data types, macrs, type cnversins, string utilities, file utilities, and a mainlp abstractin. It wrks n many UNIX-like platfrms, Micrsft Windws, OS/2, and BeOS. The OpenSSL Secure Sckets Layer library implements SSL 2.0/3.0 and TLS 1.0 prtcls. Open C++ IOStreams prvides input/utput functinality within the standard C++ libraries. IOStreams is the C++ cunterpart f the standard C stdi.h library. IOStreams uses an abstractin called streams fr handling input and utput peratins n sequences f characters. STL prvides a set f well-structured generic C++ cmpnents that wrk tgether seamlessly. Of the library s many cmpnents, the principal nes are the fllwing: Algrithm is used t define cmputatinal prcedures. Cntainer is used t manage a set f memry lcatins. Iteratr prvides a means fr an algrithm t traverse thrugh a cntainer. Functin bject encapsulates a functin in an bject fr use by ther cmpnents. Adaptr can adapt a cmpnent t prvide a different interface. The Bst libraries prvide a prtable, efficient C++ surce library that wrks well with the standard C++ library. The Bst libraries supprted are: Smart pinters prvide bjects that stre pinters t dynamically allcated (heap) bjects. Six different smart pinters are prvided: scped_ptr, scped_array, shared_ptr, shared_array, weak_ptr, and intrusive_ptr. Cntainers are generic data structures capable f hlding many different types f data. The cntainers supprted by the library are the fllwing: array, dynamic_bitset, graph, multi_array, multi_index, pinter cntainer, prperty map, and variant. Math prvides special math-template functins. OpenSSL 77 GNOME 77 OpenSSL 86 STLPrt 100 STLPrt 100 Bst 100 Page 52

53 Table 4. Libraries included in OpenC/C++. Data taken frm [45]. The OpenC/C++ plugins fr the S60 SDK can be dwnladed free f charge frm its dwnlad page STLPrt STLprt is an implementatin f C++ Standard Library, as described in the INTERNATIONAL STANDARD ISO/IEC 14882:1998(E) and latest ISO/IEC 14882:2003(E). That is, it is a fully standard-cmpliant alternative implementatin f the STL. It als ffers sme riginal ptimizatins and extensins t the standard STL, such as the rpes (a special kind f strings ptimized fr cncatenatin, as its internal representatin is a binary tree f characters). The riginal STLPrt versin can be dwnladed free f charge frm the page f the prject 17. A prt t Symbian (which wrks in bth UIQ3 and S60 3 rd editin, althugh fr the latter the versin included in Open C/C++ is preferred) has been develped by Marc Jez. The final stable versin and the latest release candidate versin can be dwnladed frm its blg ustl Anther alternative is the usage f ustl. The riginal ustl 19 was brn as an alternative t the standard C++ STL. Its authr, Mike Sharv, was wrried abut the big memry ftprint f using the standard STL implementatin f GCC. Because f this, he created a new implementatin fr a subset f the standard library that shuld be fast and small in terms f size. He achieved its gal, as using the cntainers frm within the ustl requires six times less memry than using their cunterparts frm the GCC STL implementatin. This efficiency in terms f memry makes it ideal fr mbile phnes, where memry can be very limited. A prt f the ustl 1.0 fr the Symbian OS can be dwnladed fr free frm its dwnlad page 20. It wrks in bth UIQ3 and S60 3 rd Editin, and it has been released n 29 January f 2008 by a cmpany called Penrillian WINDOWS MOBILE Windws Mbile is an perating system develped by Micrsft fr mbile phnes and handheld devices. The last versin is the 6.1, althugh the last versin available in real devices as f tday is the Available at 20 Page 53

54 Brief histry f Windws Mbile The histry f Windws Mbile starts far befre its first versin was released in April 2002; it starts with Windws CE. In Nvember 1996, Micrsft released a scaled dwn versin f Windws 95, called Windws CE. The Pegasus team, respnsible fr creating the OS, have defined a set f reference requirements and asked its hardware partners t build devices meeting them. 6 OEM signed up in the prgram: Casi, Cmpaq, HP, LG Electrnics, NEC and Philips. Handheld PCs, as they were named, started t be manufactured, and they became a success. In Windws CE 2.0, the cre f the OS was changed extensively and split int mdules. Micrsft decided that the OS will nt be exclusive fr handheld PCs; cmpanies wuld be allwed t take whatever they want frm the OS and create whichever device they wanted. Fr example, ne f the new devices that wuld run Windws CE were the Palm PCs (which are like handheld PCs, but keybard-less). By that time, the nly cmpetence fr Windws CE was Psin. By the 3.0 versin f Windws CE, Micrsft decided t cmpete directly with the Palm OS based PDAs. In rder t d s, prfund changes in the interface were dne, leaving behind the similarities with the perating systems fr persnal cmputers. As a result, Windws CE 3.0 Pcket PC 2000 was released in April 2000 Pcket PC was the new name given t the Palm-sized PCs-. Hwever, Micrsft kept releasing a versin fr handheld PCs, (Windws CE 3.0 Handheld PC, Windws CE 4.0, etc). The next versin f Pcket PC 2000 was Pcket PC 2002, and the next was Windws Mbile 2003 (which was based n Windws CE 4.0). This is the first versin which was available fr smartphnes. After Windws Mbile 2003, Windws Mbile 5.0 was released in Feb It was a versin based n Windws CE 5.0, which ffered great imprvements such as fr example Mbile Direct3D (which was based n DirectX 8) r Mbile Office (the evlutin f the previus Pcket Office suite). Finally, the Windws Mbile 6.0 was released in February 2007, and it is the versin currently available in real devices. It includes new features such as AJAX, r VIP supprt. The next versin, 6.1, has already been annunced. In additin, a 7.0 versin is being develped, and it will be centered in imprving the user interface, by adding tuch and mtin gestures (view [46]. A much mre in-depth histry f Windws CE and the Windws CE-based perating systems can be read at [47]. Page 54

55 Illustratin 14. Windws CE Timeline. Graphic taken frm Wikipedia Features It has been impssible t find an fficial cmprehensive list f all the technical features f Windws Mbile, as Micrsft publishes nly the new features that cme with each versin. Frtunately, the Wikipedia article fr Windws Mbile cntains summaries fr each versin, frm which the fllwing list has been extracted. Supprt fr several screen sizes. Supprt fr several input methds, such as keybard and stylus (with handwriting recgnitin). Prvides mbile versins f typical Windws. Fr example, Windws 6.0 cmes with Office Mbile, Windws Live, Internet Explrer Mbile, Outlk, Windws Media and Micrsft SQL Server cmpact. Supprt fr advanced graphics. This can be achieved via the Direct3D Mbile API. Supprt fr Virtual Private Netwrking.VPN is a technlgy that allws creating a private netwrk which uses the traditinal Internet infrastructure. Several cmmunicatin technlgies supprted. Including Bluetth and WLAN. Supprt fr VIP with AEC. AEC is a technique f remving the ech in VIP cmmunicatins (that is, when ne end f the cmmunicatin can hear himself thrugh the telephne when its vice reached the ther end). Embedded.NET Cmpact Framewrk v2 SP2 platfrm. We will talk abut this platfrm later. Supprt fr Strage card encryptin. Page 55

56 The cncrete changes intrduced by Windws Mbile 6.0 can be fund explained with great detail at [48]. There are three editins f the Windws Mbile 6 OS: Classic, Prfessinal and Standard (frm[49]). Their differences are summarized in the fllwing table. Editin Telephne features Tuch screen supprt Previusly called Classic Pcket PC Prfessinal Pcket PC Phne Standard Smartphne Table 5. Windws Mbile 6.0 editins. It is necessary t remark that these are nly the base Windws Mbile features, licensrs f the perating system can add their wn features if they want. Fr example, HTC devices have als OpenGL ES supprt, which is nt included by default Platfrm security Like Symbian OS, Windws Mbile have a security mdel fr preventing malicius applicatins t cmprmise the user data r the integrity f the devices it is int. What fllws is an extract frm the MSDN page than can be reached at [50]. The security mdel in Windws Mbile 6 is divided int three main cmpnents: Applicatin executin security. Applies t cde executin. It cntrls the applicatins that can run n the device. Cntrls what applicatins can d. Device cnfiguratin security. Applies t device management security. It cntrls wh can access t specific device settings. Cntrls the level f access t device settings. Remte access security. Remte API (RAPI) cntrl thrugh ActiveSync. It cntrls what desktp applicatins can d n the device. Security plicies can be applied t these cmpnents, s if a user r applicatin is allwed access, security plicies then cntrl the bundaries fr actins, access and functinality. In rder t d s, rles and certificates are taken int accunt. Certificates are used t assciate an applicatin with its rigin, and depending f this rigin the applicatin can have a different rle. The first part f a security plicy is t define the s-called access tiers. The fllwing table describe them in detail. Page 56

57 Security plicy settings Descriptin and Behavir One-tier access A ne-tier applicatin just verifies if an applicatin can be run based n its sign, withut taking int accunt permissin restrictin. Crrectly signed applicatins They can execute withut further checks. They will have the MANAGER rle. They can access the entire system. Incrrectly signed r unsigned applicatins Further checks need t be perfrmed. Tw-tier access A device with tw tier access restricts applicatin start and run-time permissins. Crrectly signed applicatins They execute withut further checks. There is a distinctin depending n the certificate: Applicatins with the Privileged Executin Trust Authrities certificate They have privileged permissins They have the MANAGER rle. Other applicatins They have nrmal permissins They have the USER_AUTH rle. Incrrectly signed r unsigned applicatins Further checks need t be perfrmed. Table 6. Windws Mbile access tiers. After applying the access-tiers plicy, if mre checks need t be dne, the next step in a security plicy is t determine whether unsigned applicatins can execute r if the user shuld be prmpted befre an unsigned applicatin executes. The applicable security levels are: Page 57

58 Security level Security ff One-tier prmpt Tw-tier prmpt Mbile2Market lcked (tw access-tier nly) Lcked Table 7. Windws Mbile security levels. Descriptin Bth signed and unsigned applicatins are allwed t run with n further security checks and withut prmpting the user. (This is a ne-tiered plicy.) Any applicatin can call any API, and mdify any part f the registry and file system. The device prmpts the user befre allwing unsigned r incrrectly signed applicatins t run. Once the applicatin is running, it has full permissins n the device. The device prmpts the user befre allwing unsigned r incrrectly signed applicatins t run. Once the applicatin is running, it has nrmal permissins. Unsigned applicatins are nt allwed t execute. Market2Market certificates have been remved frm the device, but OEM, Mbile Operatr, r Enterprise certificates are present. This plicy can be set by the manufacturer. Based n this rules, an applicatin can have ne f three pssible permissins: Privileged: Applicatins running at the privileged level have the highest permissins. They can call any API, write t all areas f the registry (including prtected areas), and have full access t system files. Applicatins running privileged can als install certificates n the device. Privileged applicatins can switch t run kernel mde. Nrmal: Applicatins running nrmal cannt access prtected registry keys and system APIs. Mst applicatins run nrmal. They cannt call trusted APIs, write t prtected areas f the registry, write t system files r install certificates t prtected stres. They can install a certificate t the MY stre. Blcked: Applicatins d nt run if blcked because they are nt allwed t execute. An applicatin culd be blcked because it is nt signed by an apprpriate certificate, because the user blcks it after being prmpted, and s frth. Page 58

59 Apart frm signing applicatins, it might be required by the security plicy that CAB files are als signed. CAB files are the files used t package applicatins t be easily deplyed in the device. The fllwing plicy is applied t DLL (dynamically linked libraries): Privileged executables cannt access DLLs that have Nrmal permissins. Executables can lad Privileged DLLs, but the DLL will run at Nrmal level. This is because the privilege is assigned t prcesses rather than t mdules. Because all that, a 3D Graphics engine wuld nt need t be signed, and thus the Windws Mbile Security mdel is nt a prblem fr us. The methd f signing an applicatin is very similar t the way f ding it in Symbian. First, a certificate shuld be purchased t a Mbile2Market partner (Mbile2Market is the Micrsft Marketing and Certificatin prgram fr Windws Mbile). Then, the applicatin can be signed by using that certificate. Buying a certificate is quite expensive. The entire prcess is represented in the fllwing illustratin: Illustratin 15. Mbile2Market cde signing prcess. T summarize: Mst Windws Mbile 6 Standard devices are cnfigured with a tw-tier access mdel: Applicatins must be signed with the privileged Mbile2Market certificate t call privileged APIs. Applicatins signed with the nrmal Mbile2Market certificate can call nrmal APIs withut user permissin. Unsigned applicatins can make calls t nrmal APIs, but require the user s permissin n initial lading. Page 59

60 Mst Windws Mbile 6 Prfessinal and Classic devices are cnfigured with a ne-tier access mdel: Drivers and pre-bt applicatins require privileged mde signing. Applicatins signed with the nrmal Mbile2Market certificate can call all APIs withut user permissin. Mst Windws Mbile 6 Prfessinal devices allw unsigned applicatins t call all APIs with a single user permissin at initial lad. Hwever, mbile peratrs may ship future devices in a mde that requires signing fr executin Prgramming languages In rder t develp fr Windws Mbile, the Windws Mbile SDK is needed. It can be freely dwnladed frm the Micrsft dwnlad centre 21. There are tw versins f the SDK. Its crrespndence with each editin f Windws Mbile 6 can be fund in the fllwing table: Windws Mbile 6 editin SDK Standard Standard Classic Prfessinal Prfessinal Prfessinal Table 8. Windws Mbile 6 editin and SDK crrespndence. The SDK requires Visual Studi 2005, standard r abve. The free express editins are nt supprted. It is pssible t develp fr Windws Mbile in several languages; we will talk abut them in the fllwing lines, by summarizing what is said in [51] Visual C++ Visual C++ is the native language f Windws Mbile. That is, it is cmpiled int machine cde. It is exactly the same Visual C++ language that is used in the PC platfrm. It allws access t the entire system API, which is a subset f the Win32 API used in the PC versin, but with sme extensins t allw using Smartphne-specific features) Visual C# and Visual Basic These are managed languages. They are easier t use, as they prvide supprt fr Cmpact Framewrk. Applicatins develped in these languages are nt cmpiled t machine cde, but int a bytecde called CIL that is later interpreted by a virtual machine called CLR. The cunterpart t being easier t use is that applicatins develped with these languages are slwer than thse written in native cde. The.NET Cmpact Framewrk is a set f classes that perfrms cmmn tasks, such as using user interfaces, use cryptgraphic functins, netwrk cmmunicatin, etc. It is a subset f Framewrk that is available fr the PC platfrm. 21 Page 60

61 Client-side Jscript Jscript is a super-set f the widely knwn JavaScript language. Jscript cde is interpreted by the web brwser, and can nly access lcal data thrugh ckies and lacks access t the OS API as well. It is abslutely unsuitable fr a prject such a graphics engine ASP.NET ASP.NET can be used t develp web applicatins by using Visual C# r Visual Basic. As ur prject is nt a web applicatin, this language is nt an ptin fr us Migratin pssibilities One f the majr strengths f Windws Mbile is its similarity with the PC Windws family. The prgramming languages are the same, the system API (WIN32) that is used by native cde is a subset f the PC versin with sme extensins t use Smartphne-specific features, and Cmpact Framewrk used by managed cde is als a subset f Framewrk available in the PC OS, als with extensins. This means that it is very easy t migrate frm the PC t the mbile versin, by just rewrking the cde f sme specific parts that are utside their mbile versins. In additin, it wuld be highly advisable t mdify the prted applicatin s that it uses and take int accunt the features f the mbile devices. Infrmatin abut thse features can fund at [52]. Cncerning migratins frm POSIX envirnments (such as Linux r Mac OS), Windws Mbile des nt seem t supprt it, s a cmplete rewrite might be needed OTHER OPERATING SYSTEMS / PLATFORMS What fllws is a brief descriptin f thse perating systems that fr sme reasns were cnsidered nt interesting fr ur prject. There are even mre perating systems than the nes mentined here. A mre cmprehensive list can be fund at [53] BREW BREW (which stands fr Binary Runtime Envirnment fr Wireless) is a develpment platfrm created by Qualcmm in 2001 t be used in their devices. It is knwn as the pseud-os, as it is really a middleware that stands between the applicatins and the ASIC (Applicatin-Specific Integrated Circuit). BREW has versins f bth OpenGL ES and M3D, s it is pssible t create a graphics engine fr it. What is mre, there is a cmplete gaming platfrm fr BREW, which is accessible thrugh BREW gaming Page 61

62 The prblem with BREW is the develpment prcess. Develpers are required t register with BREW (incurring in a fee f $400) in rder t be able t deply the applicatin in a real device. This is unacceptable fr ur prject, and the reasn why BREW was early discarded as a ptential platfrm fr ur engine. Mre infrmatin abut BREW and its develpment prcess can be fund in [54] r in the fficial BREW hmepage Palm OS / Garnet OS The Palm OS (which is nw licensed under the name Garnet OS) is an perating system that was develped by Palm Cmputing and that is currently licensed by ACCESS systems althugh it was created by Palm Cmputing, a divisin f US Rbtics-. A lt f infrmatin abut the OS and a full list f its features can be fund in [55]. Hwever, which is relevant fr us is that this perating system lacks gd 3D graphics API supprting hardware acceleratin (it has neither OpenGL ES nr Mbile DirectX supprt). There was, hwever, an early attempt t create such an API fr PalmOS (called minigl, which can be fund in its wn prject web page 24 ), but the prject was abandned. Because f this reasn, the lack f hardware acceleratin supprt, this OS was als discarded fr ur purpses very early. Mre infrmatin is available at the fficial Garnet OS hmepage BlackBerry OS BlackBerry OS is the perating system used in the BlackBerry handheld devices, manufactured by Research In Mtin Inc, thus used in a very limited number f devices. This OS ffers MIDP 2.0 and WAP 1.2 supprt as well as certain BlackBerry prprietary APIs t develpers in which is called the BlackBerry JDE API, which can use them t create Java applicatins. The latest versin is the API, and a cmplete reference can be fund at its API reference 26. It was released in June 8, 2008 and it still lacks supprt fr any 3D API (remarkably Mbile 3D, which was annunced in the press release f [56]). This is the reasn why BlackBerry was discarded. The Blackberry Develper page 27, the fficial BlackBerry OS hmepage have mre infrmatin, in case f interest Page 62

63 Mbilinux Mbilinux is the leader Linux distributin amng smart phnes. It was created by MntaVista in The current versin is the 5.0, which has supprt fr the Linux Kernel and includes glibc and the native POSIX Thread Library, which make it a perfect ptin fr prting Linux applicatins. Mre details abut this OS can be fund at [57]. The main prblems with this OS are that it is difficult t find infrmatin abut devices using it, and that it seems nt t have supprt fr 3D graphics. The fficial Mbilinux hmepage is available at the page f MntaVista iphne OS The iphne OS is the perating system f the Apple iphne and the ipd tuch. It is designed t supprt advanced input devices such as the famus multi-tuch screen f the iphne. It supprts OpenGL ES, which make it suitable fr advanced 3D graphics. Hwever, there are three main reasns because f why this OS was discarded. Firstly, Apple des nt fficially supprt the installatin f third-party applicatins n the phnes and they even said that native applicatins will likely break n the event f an OS update (view [58] fr mre details). Secndly, the first SDK appeared t late t be taken int accunt (cncretely in the 6 th March 2008); what is mre, at the time f writing this lines there is nt even a final versin, but the beta 8 is the last versin available. Finally, this OS nly supprts tw real devices at the mment (which is still relevant even taking int accunt the verwhelming ppularity f the iphne). The iphne Develper Centre 29 can be cnsidered the fficial iphne OS hmepage, where mre infrmatin can be fund Andrid Andrid is an perating system fr mbile devices based n Linux develped by Ggle and the Open Handset Alliance a cnsrtium f 34 relevant cmpanies f the wrld f telecmmunicatins-. It was first annunced in 5 Nvember 2007, and the first SDK fr the Operating System was released just a week later. The SDKs, hwever, are still in a very early stage, and applicatins develped with a versin f the SDK might nt wrk in further versins. Andrid supprts OpenGL ES, but the usage f Andrid was discarded because f the inexistence f a final versin and real devices using it the first phne using Andrid was ging t be the HTC Dream 100 (als called T-Mbile G1), which was released n Octber f Page 63

64 Please, refer t the fficial Andrid hmepage 30 fr further infrmatin MARKET STUDY Finally, it is imprtant t take the market situatin prir t decide which Operating System t target in a new develpment. Accrding t [59], by the third quarter f 2007 Symbian was the mst used perating system by far (except in Nrth America, where Micrsft with Windws Mbile-, RIM with Blackberry- and Apple with the iphne OS- are preferred). The fllwing illustratin, taken frm that results reprt, shws that situatin: Illustratin 16. Smartphne sales by OS, brken dwn by year and regins. Surce: Canalys. There is nt a newest market study available as f Nvember Page 64

65 3.4 MOBILE PHONES As it has been said, it is pssible t develp applicatins that can be run in multiple devices at the same time. Hwever, it is imprtant t chse a target device, especially in applicatins as demanding as 3D graphics engines, s that a reference f what is manageable and what is nt is available at the time f taking decisins during develpment. Fr this reasn, the fllwing sectin will analyze the situatin f the hardware market cncerning smart phnes, as a prir step t cmpare five pwerful smart phnes. This shuld give us an verview f the capabilities f smart phnes nwadays, as well as infrmatin s that an apprpriate target phne fr ur engine is chsen later PHONE CATEGORIES Mbile phnes can be classified int three different categries accrding t their features ([17]). These categries are basic phnes, feature phnes and smart phnes. Basic phnes are thse whse primary and almst unique- utility is t use telephny services. They have a very limited hardware in terms f prcessing pwer, memry and display capabilities-. Usually, they are als clse systems, which nly allw first-party sftware. Feature phnes are thse whse capabilities g beynd making and receiving calls and SMS. These phnes are the mst widespread, which make them very interesting fr new develpments. Finally, the smart phnes are the mst pwerful devices. They can be seen, indeed, as mbile cmputers with phne capabilities. They have pwerful prcessrs, plenty f memry, large screens and great cnnectivity and multimedia capabilities. In fact, the smart phnes include the latest technlgy in mbile phnes. Their main prblem is that they are priced accrdingly, which is why they are nt as cmmn as feature phnes. As that is nt a cncern fr us, we will fcus n smart phnes s we have access t state f the art technlgy and features HARDWARE The mbile phnes hardware is quite different frm the PC hardware. It is, hwever, imprtant fr us t have a brief understanding f the hardware state f the art, in rder t understand what can be expected frm current and future mbile devices. In the fllwing lines, we will explain briefly the state f the art f the hardware related t 3D graphics, such as the memry, CPU and GPU Prcessing pwer Mbile phnes have t be small, which impse severe limitatins t the circuits they can have inside them. Firstly, there is very little space in which all the hardware has t be placed. Secndly, there is n much area available fr heat dissipatin. Hwever, technlgy has advanced greatly since the first phnes, and nwadays there are phnes with ne r tw prcessrs, as can be seen in the fllwing illustratin. Page 65

66 Baseband Prcessr Applicatin Prcessr Baseband Prcessr CPU DSP CPU DSP CPU DSP GPU IVA IVA Memry Memry Illustratin 17. Typical architectures f smart phnes (left) and feature phnes (right). The cmpnents depicted in the Illustratin 17 are: Prcessrs Baseband prcessr. This prcessr is in charge f the real-time peratins that must be dne in the device, such as prcessing speech and radi signals. In basic and feature phnes, it is als respnsible fr running the perating systems, applicatins and the user interface, but at a lwer pririty. Applicatin prcessr. Where present, this prcessr is in charge f running the perating system, applicatins and the user interface, thus relieving the baseband prcessr frm these tasks. Cmpnents CPU. Central Prcessing Unit. Prcessr in charge f running the instructins. Sme CPUs have an FPU inside t perfrm flating-pint peratins. Others dn t. DSP. Digital Signal Prcessr. Prcessr that digitalizes analg signals vice, in the case f mbile phnes. GPU. Graphics Prcessing Unit. Prcessr that perfrms graphics peratins that wuld therwise be dne by the CPU. It is als called graphics accelerating hardware. IVA. Imaging and Vide Acceleratr. Prcessr that perfrms certain peratins related t imaging and vide playback such as vide decding- at high speeds. Whether a cncrete device has bth baseband and applicatin prcessrs r nt is, frtunately, irrelevant t develpers, as in either case applicatins are always run in a single prcessr. In the case f having bth, these prcessrs can be built separately -as in the iphne, which thught t have a Samsung S5L8900 applicatin prcessr and an Infinen PMB8876 S- Gld 2 baseband prcessr- r tgether in a single SC as in the Nkia N95, which has a Texas Instruments OMAP A SC which stands fr System-n-chip- is an integrated chip in which several cmpnents f a cmputer r electrnic system are integrated. The fllwing illustratin is the scheme f the OMAP 2420 cmpnents. Page 66

67 Illustratin 18. OMAP 2420 cmpnents. Illustratin taken frm [60]. Mre ften than nt, phne manufacturers d nt disclse the cmpnents f their mbiles, but nly their features. There are, hwever, peple which disassembly the mbile phnes t lk at the serigraphy f their chips and identify them. There are als enterprises specialized in this prcess called teardwn- such as Semicnductrs Insights 31 r Prtelligent 32.Teardwn examples f the Apple iphne and the Nkia N95 can be seen in the fllwing pages. There are several manufacturers f micrchips fr mbile phnes Samsung, Qualcmm, Texas Instruments, Freescale, Intel, etc-; hwever, there is a clear winner with respect t instructin sets which is what really matters frm a sftware pint f view-: ARM. Accrding t PDAdb 33, there were 615 mbiles phnes using the ARM instructin set released since January 2006, nly 1 using the 68K set, and 3 MIPS; n mbiles using neither x86 nr SuperH were released. Cncerning clck speeds, there are prcessrs up t 806 MHz nwadays in the LG KC-1- but nrmally they are in the MHz range. It is remarkable that until recently there were n flating-pint supprt in the prcessrs used in mbile phnes. Hwever, the first mbiles with FPUs such as the ARM VFP- have been released. It is freseeable that new smart phnes will have increased clck speeds and integrated FPUs Page 67

68 Regarding memries, there are fur main types f memries within a smart phne: caches, internal/massive, ROM and RAM memries. The mst cmmn type f ROM and massive strage memries is Flash EEPROM, cncretely f the NAND type. The amunt f ROM/internal memry heavily depends f the device, frm 64 MiB t 16 GiB. As fr RAM memries, SDRAM is usually used, with amunts ranging frm 64 MiB t 128 MiB, althugh mbiles with 256 and 288 MiB have been annunced t be released by the end f this year (2008). The trend is t greatly imprve memry sizes, and better technlgies such as DDR SDRAM are als reaching the smart phne market, increasing memry speeds als. Page 68

69 Illustratin 19. Nkia N95 teardwn. Illustratin taken frm [61]. Page 69

70 Illustratin 20. Apple iphne teardwn. Illustratin cmpiled frm images taken frm [62] Graphics hardware One f the mst decisive hardware fr 3D graphics even mre than the prcessr and the memry- is the graphics hardware. Cncretely, the presence f a GPU graphics prcessing unit- inside a mbile phne bsts its 3D graphics perfrmance t new levels. In the fllwing pages, GPUs used fr smart phnes frm the three majr cmpanies will be briefly presented. There are many ther lw-pwer GPUs that will nt be mentined such as the ARM Nrway Mali as they are nt used in smart phnes but n ther devices such as GPS-. It is als imprtant t remark that nly GPUs with hardware 3D acceleratin will be mentined; graphic cntrllers withut it will nt. Page 70

71 Imaginatin PwerVR MBX and SGX families PwerVR 34 is a divisin f Imaginatin Technlgies that develps bth hardware and sftware IP intellectual prperty- fr 2D and 3D rendering. While it was nce ne f the cmpetitrs in the market f 3D graphics fr PC, they left it because their inability t cmpete with nvidia and ATi. Since then, the divisin has been fcused n the lw-pwer market, such as PDAs and Mbile phnes. It shuld be highlighted that PwerVR d nt manufacture their prduct; it license them t thers such as Intel, Texas Instruments fr their wn SC Systemn-chip. A fr tday, there are tw families f PwerVR hardware acceleratrs fr mbile devices: the MBX and SGX families. The MBX family presents the fllwing features [63]: 4th generatin tile-based deferred rendering. This technlgy greatly reduces the bandwidth required fr advanced 3D graphics. The display is split int rectangular sectins (tiles). When the GPU is fed with plygns, it saves a list f triangles verlapping each tile. When all plygns have been sent t the GPU, it starts the rendering prcess thus, the render is deferred-. The render is dne in a per-tile basis, the memry needed fr its wn render can be placed n-chip, which reduces the need fr cmmunicating with external memries. In additin, textures are nt applied until the Z-Buffer prcessing is dne deferred texturing- s n cycles are wasted calculating textures fr nn-visible plygns. PwerVR Vertex Gemetry Prcessr (VGP). It is a prgrammable flating-pint SIMD cprcessr designed fr gemetry prcessing, including transfrmatin and lighting. Wide industry-standard API and OS supprt. The GPUs are cmpatible with OpenVG, OpenGL ES 1.1 and Direct3D Mbile. Sftware Develpment Kits are available fr Linux, Symbian OS and Windws CE-based systems. PwerVR internal True Clr. Clr peratins n-chip are always perfrmed at 32-bpp. PwerVR Texture Cmpressin (PVRTC). It is a patented ryalty-free cmpressin algrithm fr texture that allws smaller memry ftprints. Advanced full-scene anti-aliasing (FSAA). Lw pwer cnsumptin. There tw variants f the MBX, the MBX and the MBX Lite. Bth share a similar architecture, but the Lite versin is less pwerful due t having lwer pwer cnsumptins and die area. Bth versins are synthesizable up t 133 MHz in 130 nm and 233 MHz in 90 nm. Their perfrmance at 200 MHz ranges frm 3.4 t 7.4 millin triangles per secnd and 207 t 600 millin pixels per secnd, in typical usage cnditins. 34 Page 71

72 The SGX family, in cntrast with MBX, ffers a prgrammable pipeline MBX has a fixed ne-. Its main features are [64]: Fully prgrammable GPU. The GPU is able t accelerate advanced gemetry and pixel prcessing, per pixel and vertex lighting, and even physics, vide and image prcessing. 5th generatin shader-based tile-based deferred rendering. Just as in the MBX family, but als shaders are applied t visible effects nly. Universal Scalable Shader Engine (USSE). It is a multi-threaded multimedia prcessing engine that allws fr great hardware lad balancing. Industry standard API and OS supprt. The GPU is cmpatible with OpenVG 1.0 and 1.1, OpenGL 2.0, OpenGL ES Extensin Pack, OpenGL ES 2.0, Direct3D Mbile and sme versins Direct3D 9L and 10.1 even. 32 bit IEEE flat accuracy and advanced FSAA. Lw pwer cnsumptin. Their perfrmance at 200 MHz ranges frm 2 t 100 millin triangles per secnd and 100 t 4000 millin pixels per secnd, in typical usage cnditins less than 50% shader lad-. There are seven members f the SGX family (frm [65]): SGX510 (3 MPlys/sec)(withdrawn), SGX520 (7 MPlys/sec), and SGX530 (14 MPlys/sec) fr the handheld mbile market. SGX535 and SGX540 (28 MPlys/sec) fr handheld high end mbile, prtable, MID, UMPC Ultra Mbile PC, a new device which is essentially an small tablet PC-, cnsumer, and autmtive devices. SGX540, SGX545, SGX550 (100 MPlys/sec) and SGX555 fr advanced cnsumer devices, laptp, and desktp prducts. Bth families f GPUs have been widely licensed in fact, the MBX family is referred as a de fact standard very ften thrugh specialized web pages, as several tens f millins f unites have been already sld. There is, as f the time f writing, n device in the market which uses a SGX GPU, but several f them are expected t be released in this mnth August AMD Imagen Imagen 35 is a line f multimedia prcessrs develped by ATI-which was acquired by AMD in the third quarter f Sme f these prcessrs -such as the Imagen M100 family- are System-n-chip. Others, currently discntinued, are just c-prcessrs which ffer multimedia acceleratin. The technlgy behind the 3D acceleratin is called Imagen 3D. This technlgy has evlved ver time. In the Imagen 2300, it prvided supprt fr OpenGL ES 1.0, and ffered the fllwing features (frm [66]): 35 Page 72

73 Cmplete gemetry prcessing and pixel rendering pipeline Texture cmbine & mipmap Per-pixel perspective crrectin Bilinear and trilinear filtering Dithering Vertex fg, specular clr and Alpha blending 8/16-bpp destinatin 8/16-bpp texture, palletized texture This technlgy has nt nly be delivered within the Imagen 2300, but als as part f Qualcmm chipsets such as the MSM7xxx currently used in the HTC Tuch Diamnd, fr example. This was pssible due t cllabratin between ATI and Qualcmm (see [67] fr mre details). The fllwing chip t deliver the Imagen 3D technlgy was the Imagen 2380/2388. This time, it was the first hardware 3D acceleratr that supprted OpenGL Extensin Pack (data frm the prduct brchure, available at [68]). A new Imagen prduct ffering the Imagen 3D technlgy is currently in develpment, the Imagen Z460. It has been annunced that it will supprt OpenGL ES 2.0 ([69]). Once again, Qualcmm has licensed ATI technlgy fr their future develpments, as can be read in [70] Nvidia GFrce and Tegra prcessrs. Nvidia 36, the main cmpetitr f ATI in the PC market, has als their wn line f mbile Their first prducts were the GFrce prcessrs. Sme f them were equipped with 3D graphic acceleratin, such as the GFrce 4800 and the GFrce 5500 (which was three times faster than its predecessr, being able t prcess 2.6 millin triangles per secnd). Bth GPUs supprt OpenGL 1.0 nly. Examples f smart phnes using GFrce GPUs are the C2 XDA Flame, I-Mate Ultimate 6150, the I-Mate Ultimate 8150 and sme thers. Nwadays, Nvidia is fcused n a new line f prcessrs called Tegra. The Tegra APX 2500 is a new graphics prcessr, which cmbines IVA Imaging and Vide Acceleratr- and GPU capabilities. The GPU, called ULP GeFrce Ultra Lw Pwer GeFrce- prvides OpenGL ES 2.0 and Direct3D Mbile supprt, and it has a prgrammable pipeline that is, prgrammable shader, vertex and lighting supprt. The Tegra 600/650 series is a mre cmplete prcessr, being a true System-n-chip. It has als the ULP GeFrce GPU. Tegra prducts nly supprt Windws Mbile, are there are n mbile using them as f nw. 36 Page 73

74 3.4.3 PERFORMANCE BENCHMARKS In rder t test and cmpare the graphics perfrmance f different mbile devices, it is necessary t run a test-suite n them. This prcess is als called benchmarking, and the applicatin used is called benchmark. There are just a few benchmarks fr mbile graphics available as it is a field that is still in its early beginnings-. These benchmarks are: JBenchmark. It is an applicatin develped by Kishnti Infrmatics. JBenchmark is a suit f benchmarks aimed t test the perfrmance f the Java platfrm f different devices. Amng its tests, there is ne called JBenchmark HD that tests the quality and perfrmance f the M3G implementatin f the device. It is pssible t dwnlad the applicatins r see the results frm its webpage 37. GLBenchmark. It is als develped by Kishnti Infrmatics. GLBenchmark can test the OpenGL ES capabilities f different devices. There are versins fr Symbian (UIQ, and S60) and Windws Mbile. There are editins fr testing OpenGL ES 1.0, 1.1 and 2.0, althugh the latter is still nt available fr free. Again, it is pssible t dwnlad the applicatins r see the results frm its webpage 38. Visual Spaghetti Benchmark. This applicatin develped by Visual Spaghetti is aimed t test the graphic capabilities f devices running Windws Mbile. Unfrtunately, it is nly able t test 2D graphics, s it is f n use t us. Fr mre infrmatin abut VSBenchmark, please refer t its webpage 39. 3DMark Mbile ES. This is the name f tw benchmarks created by Futuremark, the leader in 3D graphics benchmarking in the PC platfrm. There are tw versins, ne testing OpenGL ES 1.1 and ther testing OpenGL ES 2.0. Disgracefully, they are nly available t members f the BDP prgram f Futuremark. Because f this reasn, these tests are inaccessible fr us. Mre infrmatin abut these benchmarks can be fund in the prduct page f Futuremark 40. As it can be inferred frm the list abve, there is nt a free benchmark available fr testing the perfrmance f smart phnes using the Direct3D Mbile API. Nevertheless, this shuld nt be a prblem as hardware accelerated mbiles which are thse that interest us the mst- are likely t supprt bth BEST MOBILES FOR 3D GRAPHICS The previus analysis f separate hardware cmpnents is nt enugh, as due t pwer cnsumptin, size r ther reasns, sme cmbinatins f hardware might be impssible Page 74

75 Because f that, it is imprtant t analyze cmplete devices, t fully understand the current state f the art f smart phnes. The fllwing table shws the main features f the mst pwerful and ppular smart phnes as f August Much mre in-depth infrmatin f these devices and many thers can be fund at 42. Mdel Apple iphne HTC Tuch Nkia N82 Nkia N93 Nkia N95 8GB 3G 16GB Diamnd P3700 Release Date: July, 2008 June, 2008 December, 2007 July, 2006 Octber, 2007 Manufacturer: Apple High Tech Nkia Nkia Nkia Cmputer Dimensins 62.1 x x 51 x 102 x x 112 x x 118 x x 99 x 21 mm (width x height x depth): 12.3 mm mm mm mm Mass (including battery): 133 grams 110 grams 114 grams 180 grams 128 grams Sftware Envirnment Embedded OS: Micrprcessr, Chipset CPU: Apple Mac OS X v2.0 (ARM) 32 bit Samsung S5L8900 Micrsft Windws Mbile 6.1 Prfessinal 32 bit Qualcmm MSM7201A Symbian OS 9.2 Series 60 3rd Editin Feature Pack 1 32 bit Texas Instruments OMAP 2420 Symbian OS 9.1 Series 60 3rd Editin 32 bit Texas Instruments OMAP 2420 Symbian OS 9.2 Series 60 3rd Editin Feature Pack 1 32 bit Texas Instruments OMAP 2420 CPU Clck: 620 MHz 528 MHz 332 MHz 332 MHz 332 MHz CPU Cre: ARM1176JZF-S ARM1136EJ-S ARM1136 ARM1136 ARM1136 Instructin set: ARMv6 ARMv6 ARMv6 ARMv6 ARMv6 Memry, Strage capacity ROM type: Flash EEPROM Flash EEPROM Flash EEPROM Flash EEPROM Flash EEPROM ROM capacity: MiB 4352 MiB 256 MiB, 100MiB accessible 128 MiB, 50MiB accessible 8448 MiB, 8300MiB accessible RAM type: SDRAM DDR SDRAM SDRAM SDRAM SDRAM RAM capacity: 128 MiB 192 MiB 128 MiB, 90MiB accessible 64 MiB 128 MiB, 90MiB accessible 41 Since August, new mbile phnes has been released, remarkably the successr f the Nkia N95, which is called N96. Strangely enugh, this new phne des nt have 3D graphics acceleratin, s anyne it wuld nt have been an apprpriate candidate fr us. 42 Page 75

76 Graphical Subsystem Display: clr transflective TFT clr transflective TFT clr transflective TFT clr transflective TFT clr transflective TFT Display Clr Depth: 24 bit/pixel ( scales) 16 bit/pixel (65536 scales) 24 bit/pixel ( scales) 18 bit/pixel ( scales) 24 bit/pixel ( scales) Display Diagnal: 3.5 " (89 millimeters) 2.8 " (72 millimeters) 2.4 " (61 millimeters) 2.4 " (61 millimeters) 2.8 " (72 millimeters) Display Reslutin: 320 x x x x x 320 Graphical Cntrller: PwerVR MBXLite with VGPLite Q3Dimensin MSM7500W PwerVR MBX with VGP PwerVR MBX with VGP PwerVR MBX with VGP Vide ut: Nt supprted Nt supprted NTSC/PAL, Prprietary cnnectr GLBenchmark HD 1.1 NTSC/PAL, Prprietary cnnectr NTSC/PAL, Prprietary cnnectr 1728 frames Nt supprted 1779 frames 2103 frames 1766 frames J Benchmark N infrmatin N infrmatin 937 frames 566 frames 932 frames Audi Subsystem Audi Channel(s): stere stere stere stere stere Recrding (A/D): N infrmatin 16 bit, Hz N infrmatin Hz N infrmatin Playing (D/A): 16 bit, Hz 16 bit, Hz 16 bit, Hz 16 bit, Hz 16 bit, Hz Micrphne: mn mn mn stere mn Speaker: mn mn stere mn stere Audi Output: 3.5mm Prprietary 3.5mm Prprietary 3.5mm Cellular Phne Cellular Netwrks: Cellular Data Links: GSM850, GSM900, GSM1800, GSM1900, UMTS850, UMTS1900, UMTS2100 CSD, GPRS, EDGE, UMTS, HSDPA GSM900, GSM1800, GSM1900, UMTS900, UMTS2100 CSD, GPRS, EDGE, UMTS, HSDPA GSM850, GSM900, GSM1800, GSM1900, UMTS2100 CSD, HSCSD, GPRS, EDGE, UMTS, HSDPA GSM900, GSM1800, GSM1900, UMTS2100 CSD, HSCSD, GPRS, EDGE, UMTS GSM850, GSM900, GSM1800, GSM1900, UMTS2100 CSD, HSCSD, GPRS, EDGE, UMTS, HSDPA Cellular Antenna: Internal antenna Internal antenna Internal antenna Internal antenna Internal antenna Call Alert: 64 -chrd meldy 40 -chrd meldy 72 -chrd meldy 64 -chrd meldy 72 -chrd meldy Vibrating Alert: Supprted Supprted Supprted Supprted Supprted Speakerphne : Supprted Supprted Supprted Supprted Supprted Phne Cntrller: N infrmatin Qualcmm TI TMS320C55x TI TMS320C55x TI TMS320C55x MSM7201A (QDSP4000, QDSP5000) Cntrl Peripherals Psitining Device: Multi-tuch screen Tuchscreen Nt supprted Nt supprted Nt supprted Primary Keybard: Nt supprted Nt supprted Built-in numeric phne keybard 18 keys Built-in numeric phne keybard 20 keys Slide-ut numeric phne keybard 12 keys Directinal Pad: Nt supprted 5 -way 5 -way 5 -way 5 -way Page 76

77 Interfaces Expansin Interfaces: USB: Nt supprted Nt supprted micrsd, TransFlash USB 2.0 client, USB 2.0 client, USB 2.0 client, 480Mbit/s 480Mbit/s 12Mbit/s Prprietary USB Series Mini- USB Series cnnectr B (mini-usb) Micr-B (Micrcnnectr USB) cnnectr minisd, SDIO USB 2.0 client, 12Mbit/s Prprietary cnnectr Infrared Gate: Nt supprted Nt supprted Nt supprted IrDA bit/s (SIR/CIR) Bluetth: Bluetth Bluetth EDR EDR Nt supprted USB 2.0 client, 12Mbit/s USB Series Mini-B (mini- USB) cnnectr IrDA bit/s (SIR/CIR) Bluetth 2.0 Bluetth 2.0 Bluetth 2.0 Wireless LAN: b, g 54 Mbit/s b, g 54 Mbit/s b, g 54 Mbit/s b, g 54 Mbit/s b, g 54 Mbit/s Multimedia Telecmmunicatin Analg TV: Nt supprted Nt supprted Nt supprted Nt supprted Nt supprted Analg Radi: Nt supprted FM radi ( MHz) with RDS radi FM radi ( MHz) radi receiver FM radi ( MHz) radi receiver FM radi (76-108MHz) radi receiver receiver Satellite Navigatin GPS Prtcl: NMEA 0183 NMEA 0183 NMEA 0183 Nt supprted NMEA 0183 Cmplementary A-GPS A-GPS A-GPS Nt supprted A-GPS GPS Services: GPS Antenna: Internal antenna Internal antenna Nt supprted Nt supprted Internal antenna Navigatin Chipset: N infrmatin Qualcmm MSM7201A gpsone TI NaviLink 4.0 GPS5300 N infrmatin TI NaviLink 5.0 NL5350 Built-in Digital Camera Sensr Type: CMOS sensr CMOS sensr CMOS sensr CMOS sensr CMOS sensr Reslutin: 1600 x 1200 pixels (1.92MP) 2048 x 1536 pixels (3.15MP) 2592 x 1944 pixels (5.04MP) 2048 x 1536 pixels (3.15MP) 2592 x 1944 pixels (5.04MP) Autfcus (AF): Nt supprted Supprted Supprted Nt supprted Supprted Optical Zm: 1 x 1 x Nt supprted Nt supprted Nt supprted Macr Mde: Nt supprted Nt supprted Supprted Nt supprted Nt supprted Built-in Flash: Nt supprted Nt supprted real flash mbile light (LED) mbile light (LED) Secndary Nt supprted 640 x 480 pixel 352 x 288 pixel 352 x 288 pixel 352 x 288 pixel Camera: Pwer Supply Battery Technlgy: Lithium-in battery Lithium-in plymer battery Lithium-in battery Lithium-in plymer battery Lithium-in battery Battery Build: built-in remvable remvable remvable remvable Battery Capacity: N infrmatin 900 mah 1050 mah 1100 mah 1200 mah Additinal Details Built-in accelermeter: Supprted Supprted Nt supprted Nt supprted Supprted Special Features: GPRS Class 10, A-GPS, vice cmmand, GPRS Class 10, A-GPS, QuickGPS, HTC TuchFLO 3D (HTC Manila), HTC VueF GPRS Class B Multi-slt 32, EDGE Class B Multi-slt 32, Bluetth stere GPRS Class 11, EDGE Multi-slt Class 32, 128MB minisd in the packet, Table 9. Smart phnes cmparisn. Data taken frm [71], [72] and [73]. 3.5 OPEN SOURCE 3D GRAPHICS / GAMES ENGINES FOR PC GPRS Class 32, EDGE Class B Multi-slt 32, Bluetth stere audi prfile Finally, it is time t research abut the available pen-surce 3D graphics engine fr the persnal cmputer envirnment. There are several pen surce 3D graphics engine available. A great surce f infrmatin cncerning 3D graphics engines is the database available at [8], where there is a cnvenient list f the ten mst reviewed Open Surce engines available. Page 77

78 We lk fr a 3D graphics engine with a great set f features, strng fcus n perfrmance, well-dcumented and easy t use. In rder t be cnfident abut hw much the available engines fulfill thse requirements, extensive benchmarking and experience using them wuld be needed. Unfrtunately, there is n time enugh fr it, s in rder t make a decisin we will have t rely n the infrmatin available at their different cmmunities and specialized frums. In the fllwing table, the mst ppular engines will be presented, alng with sme first impressins. The mre interesting will be then analyzed in greater detail afterwards. The reasns why the ther engines have been discarded fr further analysis are highlighted in bld. Engine name Graphics API 43 Prgramming language Operating systems OGRE 3D OGL, DX C/C++ Windws, Linux, MacOS Irrlicht OGL, DX, SW C/C++, C#, VB.NET Windws, Linux, MacOS Crystal Space OGL, SW C/C++ Windws, Linux, MacOS Panda3D OGL, DX C/C++, Pythn Windws, Linux, SunOS Iquake3 OGL C/C++ Windws, Linux, MacOS, Slaris jme OGL Java Windws, Linux, MacOS Cmments Greatest feature set. Great cmmunity. Gd dcumentatin. Gd feature set. Great cmmunity. Gd dcumentatin. Easy t use. Includes sftware rendering. Gd feature set. Small cmmunity and little dcumentatin. It is meant t be used with Pythn. Nt easy t use. Imprved versin f the id Tech 3 engine. Small cmmunity and little dcumentatin. It is prgrammed in Java. It wuld need adaptatins anyway t use M3G. It is still in alpha status. Reality Factry OGL, DX C/C++ Windws Aimed twards prttyping, nt perfrmance. Only fr Windws. The Nebula 2 device DX C/C++ Windws, Linux Simple feature set. DirectX supprt nly. Small cmmunity and little dcumentatin. 43 Abbreviatins used: OGL fr OpenGL, DX fr DirectX. Page 78

79 Blender OGL C/C++, Pythn Windws, Linux, MacOS, Slaris, FreeBSD, Irix OpenSceneGraph OGL C/C++ Windws, Linux, MacOS, Slaris, SunOS, FreeBSD, Irix, Playstatin Gd feature set. It is quite big t be prted, as it is integrated with the tls. Gd feature set. Small cmmunity. Difficult t use. As it can be seen, OGRE 3D and Irrlicht can be seen as the mst apprpriate engines fr us. Crystal Space, Blender and OpenSceneGraph are als pwerful engines, but, as we are likely t need in-depth dcumentatin bth in rder t be able t understand it and migrate it crrectly, and t be able t use fr testing purpses- they can be discarded. The fllwing lines will analyze OGRE 3D and Irrlicht in greater detail, s as t be able t chse the best ne t be prted OGRE 3D OGRE 3D 44 which stands fr Object-riented Graphics Rendering Engine- is a free pen-surce 3D graphics engine. As its name states, it is nly a graphics engine, nt a cmplete game engine. This is dne by design, in rder t be as general-purpse as pssible. OGRE is ne f the mst ppular engines, prbably due t its great design, extensive dcumentatin, and impressive list f features. It has even been used in several cmmercial prjects, including games such as Ankh. The last versin f OGRE is Einhrt, released in May It has been annunced t be the last release f the 1.4.X Einhrt branch. Next versin which lacks a release date as f nw- will be the first stable release f the 1.6.X Shggt Main features Accrding t [74], OGRE 3D ffers the fllwing features: General Features: Object-Oriented Design, Plug-in Architecture, Save/Lad System Simple, easy t use OO interface designed t minimize the effrt required t render 3D scenes, and t be independent f 3D implementatin i.e. Direct3D/OpenGL. 44 Page 79

80 Flexible plug-in architecture allws engine t be extended withut recmpilatin Clean, design and full dcumentatin f all engine classes Supprt fr ZIP/PK3 fr archiving Scripting: Scripted material language allws yu t maintain material assets utside f yur cde Scriptable multi-pass rendering Physics: Basic Physics, Cllisin Detectin, Rigid Bdy: Cntrllers allw yu t easily rganize derived values between bjects Includes bindings fr multiple 3rd party cllisin / physics systems (ODE, Nvdex and Tkamak) Lighting: Per-vertex, per-pixel, light mapping. Can have an unlimited number f lights in the scene Supprted thrugh vertex and fragment prgrams. Shadws: Shadw Mapping, Shadw Vlume. Techniques supprted: mdulative stencil, additive stencil, mdulative prjective Multiple stencil shadw ptimizatins, including vertex prgram extrusin, smart light and shadw caster culling, integratin with mesh LOD, Z-Pass and Z-Fail methds, 2-sided stenciling, scissr regin clipping Texture shadws fade ut at far distance Texturing: Basic, Multi-texturing, Bumpmapping, Mipmapping, Vlumetric, Prjected Prjective texturing autmatically links with texture unit t a Frustum instance can register external texture surces in rder t feed texture data in frm anther surce Supprts PNG, JPEG, TGA, BMP and DDS image files Shaders: Vertex, Pixel, High Level: Supprts vertex and fragment prgrams (shaders), bth lw-level prgrams written in assembler, and high-level prgrams written in Cg r DirectX9 HLSL, and prvides autmatic supprt fr many cmmnly bund cnstant parameters Supprts GLSL Scene Management: General, BSP, Octrees, Occlusin Culling, LOD. Highly custmizable, flexible scene management nt tied t any single scene type. Use predefined classes fr scene rganizatin if they suit r plug in yur wn subclass t gain full cntrl ver the scene rganizatin Hierarchical scene graph Scene querying features Animatin: Inverse Kinematics, Skeletal Animatin, Animatin Blending. Page 80

81 Skeletal animatin, including blending f multiple animatins, variable bne weight skinning. Meshes: Mesh Lading, Skinning, Prgressive: Hardware-accelerated skinning Flexible mesh data frmats accepted Exprt frm many mdeling tls including Milkshape3D, 3D Studi Max, Maya, Blender and Wings3D. Surfaces & Curves: Splines. Biquadric Bezier patches fr curved surfaces Special Effects: Envirnment Mapping, Lens Flares, Billbarding, Particle System, Mtin Blur, Sky, Water, Fg. Particle Systems, including easily extensible emitters and affectrs (custmizable thrugh plugins). Systems can be defined in text scripts fr easy tweaking Supprt fr skybxes, skyplanes and skydmes, very easy t use Rendering: Fixed-functin, Render-t-Texture, Fnts, GUI. Scriptable multi-pass rendering Material LOD Supprts the cmplete range f fixed functin peratins such as multitexture and multi-pass blending, texture crdinate generatin and mdificatin, independent clr and alpha peratins fr nn-prgrammable hardware Supprt fr multiple material techniques Transparent bjects autmatically managed Fnt system: TrueType fnts and pre-created textures 2D GUI System with Buttns, Lists, Edit bxes, Scrllbars, etc Surce cde analysis Althugh it is imprtant fr us t knw hw the engine is used and what it has t ffer, it is even mre imprtant t knw hw much effrt wuld be needed t migrate it. This cannt be knwn a priri, but analyzing the surce cde f the engine we might be able t estimate it r, at least, t decide whether it wuld be easier t prt OGRE 3D r Irrlicht. The main aspects t be analyzed are the external dependencies, the verall structure and rganizatin f the engine, and which cde wuld need t be prted. In rder t have an estimate n the magnitude f the cde and thus the ptential cmplexity f migrating itsme metrics will als be prvided External dependencies OGRE 3D depends n fur cre external dependencies: Page 81

82 FreeType 45 : A library fr managing fnts. FreeImage 46 : A library fr managing image frmat such as PNG, BMP, JPEG, etc. Zlib 47 : A library fr managing cmpressed files. ZZIPlib 48 : A library fr managing Zip files Structure f the engine It is widely recgnized that ne f the strngest aspects f OGRE 3D is its design. In the fllwing illustratin, sme f the mst imprtant classes f the engine are shwn, s that its architecture can be understd. Afterwards, a brief explanatin f each cmpnent is given. Illustratin 21. Overview f the structure f OGRE 3D. Infrmatin taken frm [75] Page 82

83 Rt. This class is the entry pint t the engine. It is used t request specialized bjects t the engine, which are the nes which will d the actual wrk. Scene management. Classes f this rle are used t define the scene t be render in a mre declarative way than allwed by the lw level graphic APIs. Resurce management. Classes f this rle are used t manage the resurces needed by the scene, such as textures, gemetry r fnts. Rendering. Classes f this rle are respnsible fr getting the scene declared rendered by managing the rendering pipeline, the render states, and whatever needed. Plugins. Plugins are classes that inherit and extend ther classes f the engine, and thus prviding new functinality Cde t be prted In rder t make the engine supprt a new graphics API, a new class extending OGRE::RenderSystem and prbably certain additinal classes- wuld be required. Currently nly OpenGL and Direct3D 9 are supprted thrugh the OGRE::GLRenderSystem and the OGRE::D3D9RenderSystem classes respectively-. Cncerning perating system dependence, OGRE 3D uses macrs t select in cmpile time which cde t use. Cde exclusive fr a specific platfrm is enclsed in #ifdef OGRE_PLATFORM_XXXX #endif blcks, with XXXX being ne f WIN32, LINUX r APPLE. These blcks are scattered acrss the cde, being used whenever needed. Finally, there might be prblems with the external libraries if they are nt available fr the target platfrm. As all f them are pen surce, they culd be migrated if needed, but this shuld be taken int accunt Interesting metrics In rder t measure the cmplexity f the surce cde f the engine and the pssible required effrt needed t migrate it, surce lines f cde have been use as metrics. The fllwing figures have been btained using Cde Analyzer 49. Summary statistics fr the entire engine withut dependencies: Ttal Surce Files: 735 Ttal Lines: Cde Lines: Cde and Cmment Lines: 1510 Cmment Lines: Blank Lines: OpenGL Render System nly: 49 Page 83

84 Ttal Surce Files: 128 Ttal Lines: Cde Lines: Cde and Cmment Lines: 750 Cmment Lines: 7333 Blank Lines: 4914 Direct3D 9 Render System nly: Ttal Surce Files: 44 Ttal Lines: Cde Lines: 8158 Cde and Cmment Lines: 103 Cmment Lines: 2630 Blank Lines: 1141 It can be seen that a new render system can be quite big especially in the case f an OpenGL-based engine-. Frtunately, it might be pssible t reuse cde frm the existing nes Resurces f infrmatin 3D: There are a lt f dcumentatin and resurces f infrmatin available abut OGRE API Reference. Dcumentatin extracted frm the cmmented surce cde with Dxygen. It explains the functinality prvided by every functin and class f the engine. Manual. OGRE cmes with a manual that explains the techniques used in the engine and hw t use them effectively. Wiki. There is a wiki with plenty f tutrials and infrmatin prvided by the big OGRE cmmunity. Frum. There are fficial frums where users f OGRE can exchange infrmatin. The OGRE cmmunity is quite friendly and supprtive, thus being an invaluable surce f infrmatin in case needed. A bk. A bk entitled Pr OGRE 3D Prgramming, written by Gregry Junker is als available in case needed. Hwever, it is said t prvide nt much infrmatin than what is available n the ther resurces mentined abve Previus attempts t migrate OGRE OGRE has been migrated t a handheld device in the past. It was nt a smart phne, but a PwerPC which used Windws CE, accrding t [76]. The migratin was successful, althugh the perfrmance was nt very high due t the lack f hardware acceleratin in the target device. Page 84

85 Althugh in the end f the paper is it said that the prted engine will be made publicly available, we have been unable t find it IRRLICHT Irrlicht 50 is a free pen-surce 3D graphics engine, just as OGRE 3D althugh it includes sme extrardinary features such as basic input r cllisin detectin. It was created with the specific purpse f being easy t use withut scarifying a rich feature set, which is ne f the reasns f its ppularity. It is als knwn fr ffering high perfrmance even in lw end hardware -prbably because its riginal authr lacked gd hardware t test the engine in by the time he stated develping it-. Mac. The last versin f Irrlicht is the , released in June 2008 fr Linux, Windws and Main features Accrding t [77], Irrlicht ffers the fllwing features: General Features: Object-Oriented Design Using C++ the engine is cmpletely bject-rientated yielding platfrm independence and graphics API abstractin Integrated fast XML parser Unicde supprt fr easy lcalizatin Supprt files Supprt fr 64-bit Scripting Supprt LUA scripts Built-in Editrs irredit: a functinal free 3D scene graph editr fr Irrlicht. GUI Editr Physics: Cllisin Detectin Bunding bx and triangle based cllisin detectin and respnse Lighting: Per-vertex, Per-pixel, Light mapping Supprts dynamic lighting and light maps Supprt bump mapping / nrmal maps Supprted thrugh vertex and fragment prgrams as well as fixed functin pipeline Shadws: Shadw Vlume Dynamic shadws using the stencil buffer Texturing: Basic, Multi-texturing, Bumpmapping, Mipmapping Basic texturing supprt with texture animatin Supprt fr BMP, Phtshp, JPEG, TGA, PCX, PNG On Octber 2008, the versin was released. Hwever, this was after the develpment f the prt fr the versin was started. Page 85

86 Shaders: Vertex, Pixel, High Level Supprts lw level assembly vertex/pixel shaders and fragment/vertex prgrams as well as HLSL Supprt fr GLSL: ARB Vertex Prgrams, ARB Pixel Prgrams, HLSL, GLSL 100 & 110, VS , PS1.1 - PS3.0 Scene Management: Octrees, Occlusin Culling Easily extensible hierarchical scene graph Mix indr and utdr scene seamlessly tgether Supprts picking Animatin: Skeletal Animatin, Mrphing Meshes are linear interplated frm ne frame t the next Mesh is manipulated by animated jints Lad Quake 3 BSP Levels Meshes: Mesh Lading Supprts 3DS, Milkshape, COLLADA, Maya, DeleD, DirectX.X, FSRad.ct, Cartgraphy shp 4.csm, Pulsar LMTls.lmts, My3DTls 3.my3D, Quake 2 mdels Includes additinal exprters fr Blender, 3DSMax, Gile[s] Special Effects: Envirnment Mapping, Billbarding, Particle System, Sky, Water, Fg Sphere mapping Realistic water surfaces Custmizable Particle systems fr snw, smke, fire Supprts parallax mapping Rendering: Fixed-functin, Render-t-Texture, Fnts, GUI Terrain Rendering 2D drawing functins like alpha blending, clr key based blitting, fnt drawing and mixing 3D with 2D graphics Alpha blending fr transparency Transparent bjects autmatically managed 2D GUI System with Buttns, Lists, Edit bxes, etc Surce cde analysis As it was dne with OGRE 3D, what fllws is a brief analysis f the surce cde f the last versin f the Irrlicht engine External dependencies Irrlicht des nt have external dependencies. It uses three libraries, but they are embedded inside the engine. These libraries are: Page 86

87 Libpng 52. The fficial reference library fr managing PNG image files. JPEGlib 53. A free library fr managing JPEG image files. Zlib 54. A free library fr managing cmpressed files Structure f the engine The Irrlicht engine is structured in six different main namespaces, each related t a specific task: Irr. This is the main namespace in Irrlicht, which is further split int ther namespaces. Hwever, it des cntain certain classes and functins. Fr example, the Irrlicht device class the equivalent t the rt in OGRE- Is lcated here. Irr::cre. This namespace cntains basic classes like vectrs, planes, arrays, etc. Irr::gui. This namespace cntains the classes needed t create graphical interfaces. Irr::i. This namespace cntains the classes in charge f managing files and nly files, nt user input-. Irr::scene. This namespace cntains the classes related t the scene management. Irr::vide. This namespace cntains the classes related t the rendering f the scenes. Here is where the engine cmmunicates with the underlying graphics APIs Cde t be prted In rder t add supprt fr a new graphics API in Irrlicht, a new class inheriting frm irr::vide::ividedriver shuld be created. Currently Irrlicht has supprt fr Direct3D 8, Direct3D 9, OpenGL and a sftware renderer. With regards t the perating system and cmpiler dependencies, as it happens with OGRE, there are several cnditinal precmpiler blcks which are scattered acrss the cde. Hwever, mst f the perating system cde is lcated inside a Device in Irrlicht the nmenclature-, which is a class inheriting frm irr::irrlichtdevice. Fr bth classes, many ther helper classes might be needed Interesting metrics Once again, we get sme metrics frm the last versin f the Irrlicht surce cde in rder t be mre capable f cmparing OGRE and Irrlicht Page 87

88 Summary statistics fr the entire engine including the libraries: Ttal Surce Files: 701 Ttal Lines: Cde Lines: Cde and Cmment Lines: 9672 Cmment Lines: Blank Lines: OpenGL Vide Driver nly: Ttal Surce Files: 15 Ttal Lines: 7568 Cde Lines: 5711 Cde and Cmment Lines: 80 Cmment Lines: 600 Blank Lines: 1177 Direct3D 9 Vide Driver nly: Ttal Surce Files: 13 Ttal Lines: 5780 Cde Lines: 4034 Cde and Cmment Lines: 72 Cmment Lines: 514 Blank Lines: 1160 It can be seen that, althugh the entire engine is mre r less as big as OGRE, there is far less cde dependent n the graphics APIs Resurces f infrmatin As it happened with OGRE 3D, there are a lt f dcumentatin and resurces f infrmatin available fr Irrlicht: API Reference. Dcumentatin extracted frm the cmmented surce cde with Dxygen. It explains the functinality prvided by every functin and class f the engine. Tutrials. A sequence f tutrials f increasing difficulty is available, s that learning Irrlicht is as easy as pssible. There are als ther tutrials dedicated t different tpics such as integrating Irrlicht with ther physics engines r using Irrlicht frm different IDEs. Wiki. A wiki with even mre tutrials and infrmatin prvided by the cmmunity is als available. Page 88

89 Frum. There are fficial frums where users f Irrlicht can exchange infrmatin. As in the case f OGRE, the Irrlicht cmmunity is very friendly and supprtive, and dn t hesitate helping newcmers t the engine when asked t d s Previus attempts t migrate Irrlicht There has been at least tw previus attempts t prt Irrlicht t a mbile phne that we knw f, cncretely t the Series 60 platfrm. One prject was called mirrlicht, and there is still sme cde available in his hmepage 55. The mirrlicht prject was started in Nvember f 2006 by Li Ming, and was abandned in Octber f Sme prgress was dne in prting an unstable versin f Irrlicht between the 1.3 and the t Symbian and the 1.2 versin t Windws CE. In fact, the engine is nly able t lad and render a quake 3 map in the emulatr, but with incrrect clrs and n user interactin. The ther prject is Irrlicht-em. It appears t be stpped as f Octber It has a preliminary versin f OpenGL ES supprt with incrrect clrs- and still n supprt fr S60. There is n much infrmatin abut its develper, apart frm his/her nickname, which is cyberzeister. We sent him an asking fr sme mre infrmatin t give him/her prper credit, but it was unanswered Recently, in Nvember 2008, it has begun t shw sme activity again t late fr us, as the develpment f ur entire prt finished n Octber It is unknwn fr us which imprvements has been made t the prject since ur last review. Page 89

90 4 PROBLEM STATEMENT After the extensive research dne, it is time t define exactly what t d in this prject. In rder t d s, we have t decide which engine fr PC t migrate, which platfrm t target, which device t take as reference and which graphics API t use. Frm the infrmatin gathered, it seems that prting Irrlicht is the best ptin. The number f lines f cde, which depends n the graphics API, is far less than in the case f OGRE, which means that less cde will need t be written r mdified t use a new graphics API. The lack f external dependencies shuld als ease the migratin prcess and the final deplyment f the engine int the phne. Als remarkable is the fact that Irrlicht is fast even n lw perfrmance hardware, which is exactly what we can fund in mbile phnes as f tday when cmpared t PC hardware-. It even has sftware rendering, which culd be used in mbile phnes that lack supprt fr the cmmn 3D graphics APIs. The next questin t be addressed is the target platfrm. Bth Windws Mbile and Symbian OS seem t be suitable, as their security platfrms suppse n prblem fr a 3D graphics engine. They bth ffer mre r less the same set f features by default t what we are cncerned, s it is really difficult t decide which ne t use. Windws Mbile has the advantage that its SDK is available fr Visual C++, which supprts the same features f C++ that are used by the engine, whereas in Symbian a different versin f C++ is used. Hwever, as it has been seen, this shuld nt suppse a real issue as Symbian C++ is mstly cmpatible. What is mre, the GLQuake prt has been able t surpass this issue, which makes us cnfident f being able t d the same, with the guidance f its cde. On the ther hand, Symbian is far mre used than Windws Mbile as f tday, especially in Eurpe. In rder t break the tie between bth perating systems, we might take a lk at the different devices analyzed. It is clear that the majrity f them are Symbian-based, especially the nes with 3D graphics hardware acceleratin. Because f this reasn, Symbian has been chsen as the target perating system, being Series 60 the target platfrm. The reasns t chse the S60 ver the UIQ platfrm are basically tw: it is much mre used in fact, nne f the smart phnes analyzed used UIQ-, and it shuld be easier t migrate t S60 due t Open C/C++. As a side effect f selecting S60 as the target platfrm, it might be pssible t reuse smething frm mirrlicht, Irrlicht-em r frm the prt f the GLQuake engine. Prviding that S60 has been chsen as the target platfrm and that the Irrlicht engine is written in C++, there is really nt chice in which regards t the graphics API t use: OpenGL ES 1.1. S60 has n supprt fr Direct3D Mbile, and M3G is nly fr the Java platfrm. Obviusly, prting the entire engine t Java in rder t use M3G is nt an ptin, since it wuld mean much mre wrk in rder t get much pr results. Finally, a reference device shuld be chsen. All f the Nkia phnes yield excellent results in the 3D graphics benchmarks. The N93 is quite superir in this aspect, which wuld make it an excellent ptin. Hwever, the N95 8GB has the advantage f being available fr us Page 90

91 t test the engine in a real device. Because f this reasn, the N95 8GB wuld be ur reference device. Nevertheless, Nkia has set up an nline service called RDA that allws testing any applicatin in real devices remtely, s we might be able t test the engine in ther devices als. Mre infrmatin abut RDA can be fund at [78]. T cnclude this first step f the dissertatin, ur final prblem statement will be specified as: Prting the Irrlicht engine, versin 1.4.1, t the Series 60 platfrm. In rder t d s, the OpenGL ES 1.1 API will be used. The reference device, in which the engine shuld wrk as well as pssible, will be the Nkia N95 8GB. Page 91

92 5 PORTING IRRLICHT As it has been already said, we are ging t prt Irrlicht t the Series 60 platfrm. Due t the simplicity f ur gals we just need a wrking versin- and time cnstraints; we will nt fllw any frmal methdlgy as they wuld add mre cmplexity than required-. Hwever, a minimum preparatin is needed befre start cding in rder t have any chances f succeeding. Cncretely, we have t set which requirements we want t met, which is the scpe f the prject -and, even mre imprtant, what is utside it-, finally a plan t fllw, and the budget needed fr the prject. In the fllwing sectins, we will explain all these cnsideratins. Afterwards, we will explain the steps that need t be dne t add supprt fr the Series 60 platfrm t Irrlicht Finally, we will end shwing the results, by shwing hw t adapt the existing Irrlicht dems fr its usage in the mbile phne, and highlighting the differences between the S60 and PC versins. 5.1 PLANNING Certain planning is needed in rder t develp a prject. Cncretely, we have t set which requirements we want t met, which is the scpe f the prject -and, even mre imprtant, what is utside it-, a plan t fllw, and the budget needed fr the prject. In the fllwing sectins, we will explain all these cnsideratins REQUIREMENTS AND SCOPE It wuld be wnderful if we were able t put smething like a minimum number f plygn t supprt, r a minimum frame rate t achieve. As we are targeting a mbile platfrm, we culd even set a maximum pwer cnsumptin t have. Hwever, we cannt. Because f being nly ne develper, due t ur inexperience in the field which makes it very difficult t make reliable predictins- and abve all due t time cnstraints, the nly requirements that we will try t met are: Having the engine wrking in the N95 8GB phne. The engine might wrk in ther phnes using the S60 3 rd excludes als having the engine running in the emulatr. Editin FP1 platfrm, but it needs nt t. This Aviding mdifying the public API prvided by the Irrlicht engine as far as pssible. In case f abslutely need f mdifying it, the changes shuld be made backwards cmpatible if pssible. Keep cmpatibility with the perating systems currently supprted by Irrlicht. Hwever, the new features such as the OpenGL ES supprt- d nt need t wrk n them. Page 92

93 Secndly, we shuld set the scpe f ur prject r, mre imprtant, what is nt. We have decided that the fllwing is ut f scpe: Fixing bugs that can be fund n Irrlicht. Prbably due t nt having any unit testing methdlgy, the Irrlicht engine has several bugs f different relevance. Mst f them are fixed in every new versin f the engine, althugh alng with a new versin new bugs are intrduced, als. We will nt spend any time fixing bugs, as we need all the time we can get fr ur wn purpses. That des nt mean that we will nt fix anything if the slutin is simple enugh, f curse. Implementing new graphic techniques fr the already presented features. Irrlicht might use sme techniques that are nt pssible t prt t OpenGL ES. In rder t supprt the features that use them, it wuld be necessary t implement abslutely different techniques r even prviding sftware implementatins. This is nt acceptable fr us, as the time needed will be much mre than we can affrd, and the result might be t slw t be cnsidered usable. Because f this reasn, features that meet that criterin will be drpped. Examples f thse features are thse requiring shaders, fr example. Adding new features. It is quite bvius that the currently present features suppses an verwhelming wrk as they are, s we will nt add new features unless they are extremely justified. Create unit testing. Irrlicht des nt cme with unit tests, and it wuld be extremely time-cnsuming t create unit tests fr it right nw althugh it wuld be highly desirable-. Because f this reasn, the testing f ur applicatin will be abslutely best-effrt, withut fllwing a prper testing methdlgy. Having the engine wrking in any phne different t the N95 8GB r in the emulatr. Althugh in thery the engine shuld be able t run in any S60 3 rd Editin FP1 phne, we are nt able t ensure this. This is because we lack any ther device althugh this culd be vercme thanks t the Nkia RDA 57 prgram- and the time needed t d the apprpriate tests. Finally, it is imprtant t define a line f actin. We have already cmmented in Cde t be prted (page 87) that there are tw main part f the engine that will need t be mdified r, mre prperly, added: A Vide Driver and a Device. A Vide Driver is respnsible fr cmmunicating with an underlying graphics API t shw graphics n the screen. It ffers certain rutines t handle mdels and t create certain effects, such as shadws. A Device is respnsible fr cmmunicating with the underlying perating system. Its main tasks are t create the windw, handling events and sme mre. 57 Nkia Remte Device Access. See xperience/testing/remte_device_access/ fr mre infrmatin. Page 93

94 These are tw independent cmpnents f the engine, and we can use that fact t split ur wrk int tw different stages. One will be creating an OpenGL ES vide driver, using the current OpenGL driver as a starting pint. Once this is dne, Irrlicht shuld be able t use the OpenGL ES driver under Windws, which will let yu test the Vide Driver separately. This is quite a gd thing, as it allws us t fcus in the OpenGL and OpenGL ES differences nly, withut having t care abut platfrm differences as well. Then, the secnd part f the develpment will be t create a device fr the S60 3 rd Editin FP1 platfrm. Once this is finished, the engine shuld be able t wrk in the mbile phne, and then the develpment will be finished PROPOSED PLAN / SCHEDULE After defining the requirements and the scpe f the prject, a phase f analysis needs t be cnducted. The gal f that phase is t determine which changes wuld be needed and the time needed t learn abut them, t perfrm them and t dcument them. Once again, due t ur inexperience in all aspects f the prject (3D engines and Symbian develpment), it is imprtant that ur plan is designed s that it gives us margin fr unfreseen prblems, which are likely t ccur. Frm the results f that analysis, the fllwing plan, expressed in a Gantt diagram has been designed: Page 94

95 Page 95

96 5.1.3 BUDGET After defining the plan, we are ging t calculate the budget needed fr develping this prject Human resurces In ur case, a student f cmputer engineering has been respnsible fr develping the cmplete applicatin. The cst per hur f such a student, prviding that his final dissertatin has nt been defended yet, is Prviding that the estimated time needed t cmplete the prject is 109 days, wrking 8 hurs per day, we have the fllwing result: Name Rle / hur Hurs Ttal Cmputer engineering student All , TOTAL 19, Hardware resurces The hardware needed fr develping the applicatin includes a standard cmputer fr develpment as well as a Nkia N85 8GB fr testing. By standard cmputer, we refer t any cmputer able t run the required sftware fr the prject. Prviding that the cmpilatin times can be lng due t the size f the applicatin, it is wrth buying a fast cmputer in rder t minimize stalls. Name Descriptin / unit Units Ttal Develpment cmputer Cmputer used fr develping Nkia N95 8GB Device fr testing ADSL One mnth f ADSL line TOTAL 1, Sftware resurces Several sftware prducts are needed fr this prject. What fllws is a list with the csts assciated with them. It shuld be nted that members the Universidad Carls III de Madrid have access t a special license frm Micrsft called MSDN Academy, which allws the free dwnlad f sme f their prducts. Name Descriptin License / Units Ttal unit Micrsft Windws XP Operating system MSDN Academy Prfessinal Micrsft Wrd 2007 Wrd prcessr Retail license Micrsft Visi Standard Chart editr Retail license Micrsft Visual Studi Develpment suite MSDN Academy Page 96

97 2005 Prfessinal fr Windws Carbide.c Develpment suite Develper Develper editin fr Symbian editin license The GIMP Image editr GPL TOTAL Operatinal csts These are recurring csts assciated with the develpment f the prject, such as cnsumables and travel expenses. Name Descriptin Ttal price Paper sheets Papers fr dcumentatin Ink cartridges Ink cartridges needed t print dcumentatin 82.5 Petrl Petrl needed t ten travels t Clmenarej frm Leganés TOTAL Ttal csts Adding all the afrementined csts, we have that the entire prject can be dne with the fllwing budget: Name Ttal price Human resurces 19, Hardware resurces Sftware resurces Operatinal csts TOTAL 21, CREATION OF THE OPENGL ES DRIVER After the planning, it is time t begin the prject itself. As we said befre, the first stage in the develpment f ur prt will be t create an OpenGL ES driver. In rder t s, we will create a cpy f the current OpenGL driver, and mdify it s that it uses OpenGL ES instead t achieve the same results, as far as pssible. The fllwing sectins will explain this prcess systematically; up t the detail we cnsider enugh t allw thers t repeat ur steps. Unfrtunately, the task is quite big, cmplex, and has t deal with a great amunt f little details, s we are afraid that it will nt be an easy reading CREATING A NEW DRIVER The fllwing lines will explain hw t create a new driver, which des exactly the same as the OpenGL ne. This will be the base fr future mdificatins that will be explained later, and which will turn this new driver int a cmplete driver fr OpenGL ES 1.x. Page 97

98 Design decisin When it cmes t create a new driver fr Irrlicht using OpenGL ES there are tw pssible ptins: Creating a new, separate driver, r intrduce the needed mdificatins in the OpenGL driver and cntrl which cde is cmpiled by using macrs. Althugh frm a purist pint f view, using macrs fr cnditinal cde is a bad practice althugh it is ften unavidable, particularly in crss-platfrm cde- it is an ptin that is wrth cnsidering. A priri, OpenGL ES is very similar t OpenGL, s it is reasnable t think that bth drivers will share mst f their cde. Thus, having them as separate drivers will imply a lt f cde repetitin, which is nt gd fr maintainability. Hwever, having a single driver that can be cmpiled either as OpenGL r OpenGL ES but nt bth, means that supprt fr nly ne f them can be prvided at a time. This is a sever limitatin, as the state-f-the-art graphics hardware in mbile devices is starting t prvide supprt fr bth, OpenGL ES and OpenGL that is the case f the PwerVR SGX, fr example. Als, having tw separate drivers means that the cde is cleaner and easier t understand. Because f all this reasns, having a separate driver was preferred. The fllwing table summarizes the prs and cns f bth appraches. Having a single cnvertible driver Having tw separate drivers N cde repetitin A lt f cde repetitin It is nly pssible t supprt ne API r the It is pssible t supprting bth APIs at ther. The decisin is taken at cmpile time. the same time. The decisin is taken at run time. Mixing cde, mre difficult t read The cde is well separate, and thus it is easier t read. Table 10. Prs and cns f the different appraches fr the new OpenGL ES driver DUPLICATING THE OPENGL DRIVER In rder t create a new OpenGL ES driver, duplicating the current driver is the best way t prceed. After ding s, changes culd be made t the duplicate OpenGL driver s that wrks crrectly with OpenGL ES. T create a duplicate driver, the first step is t identify where it is lcated. The OpenGL driver is lcated in the fllwing files, all f them in the surce flder: COpenGLDriver.h COpenGLDriver.cpp COpenGLExtensinHandler.h COpenGLExtensinHandler.cpp COpenGLMaterialRenderer.h COpenGLNrmalMapRenderer.h COpenGLNrmalMapRenderer.cpp COpenGLParallaxMapRenderer.h COpenGLParallaxMapRenderer.cpp Page 98

99 COpenGLShaderMaterialRenderer.h COpenGLShaderMaterialRenderer.cpp COpenGLSLMaterialRenderer.h COpenGLSLMaterialRenderer.cpp COpenGLTexture.h COpenGLTexture.cpp After knwing this, these files have t be cpied and the new versins renamed by replacing COpenGL with COpenGLES-. The included headers in the different files have t be updated t reflect the new file names. The next step is t add these new files int the slutin. As a result f these actins, the engine has the OpenGL driver twice, nt anther driver that des exactly the same. Because f this reasn, the engine cannt even cmpile. T fix this, all classes have t be renamed everywhere, alng with their cnstructrs and destructrs which can be easily dne by replacing every instance f COpenGL by COpenGLES in the files-. The macr that decides whether the files f the driver are cmpiled r nt has t be changed t, frm _IRR_COMPILE_WITH_OPENGL_ t _IRR_COMPILE_WITH_OPENGL_ES_. It is als very imprtant t ensure that the guardians f the header files are different frm thse f the riginal driver, s as t avid cnflicts in the future. Once new driver is nw dne; the next thing is t make it available frm t the engine users. The first thing t d is t create a new element in the vide::e_driver_type enumeratin, which can be lcated in include/edrivertypes.h. This enumeratin can be used by the end users at runtime t identify which driver they want t use. The new element will be called EDT_OPENGLES. There are sme methds f different classes f the driver that used EDT_OPENGL in sme way; changing them t use the new element is required. These methds are: vide::copenglesdriver::settexture() vide::copenglesdriver::getdrivertype() vide::copenglesdriver::setrendertarget() vide::copenglestexture::getdrivertype() After ding this, it is time t create the functins required t create an instance f the driver. The fllwing calls are dne in rder t create it, since the user calls a functin in the Irrlicht API until the cnstructr f the OpenGL driver is called. In the example, the Windws device will be used: The user calls irr::createdevice() r irr::createdeviceex() (1) This creates an instance f the platfrm device (irr::cirrdevicewin32) (2) The methd createdevice() f the device is called. (3) Depending n the type f driver Different functins are called. In ur case the functin which creates the driver is Page 99

100 called vide::createopengldriver(). (4) This functin calls the cnstructr and any ther initialized functin required by the driver. (5) Pseud cde 1. Functin calls since the user ask fr a driver creatin until it is actually created. The functins mentined in (1) are the nes declared in the public API and thus the nly nes the end user can call directly. They are defined in the cde f the device f the platfrm t which the Irrlicht engine has been cmpiled. Because f this reasn, it is clear which platfrm device t instance in (2). The first place that needs t actually knw abut the existence f the new driver is the functin mentined in (3). It receives as a parameter the vide::e_driver_type enumeratin used by the user t specify which driver he wants. Depending n its value, it calls ne functin r anther. It is necessary t update the functin s that it takes int accunt the new value f the enumeratin, in which case instead f calling the functin depicted in (4) it has t call anther functin which will be called vide::createopenglesdriver().this functin shuld be defined in the driver, and is respnsible fr instancing and initialize the driver. As we are wrking with a duplicate f the OpenGL driver, the nly thing that needs t be dne is t rename the vide::createopengldriver() functin that is currently available there. Nte that a declaratin fr the functin shuld be added in the file f the Windws device, surce/cirrwin32device.h. Finally, as it was dne in (5), this functin shuld call tw functins. In ur case, they are the vide::copenglesdriver() cnstructr, and the vide::copenglesdriver::initdriver() functin. After all this, the nly thing remaining is t define a new pre-prcessr macr called _IRR_COMPILE_WITH_OPENGL_ES_ in the file include/irrcmpilecnfig.h s that the new driver is cmpiled. It is pssible that the new driver and the ld ne present sme name clashes. If that is the case, this can easily be slved by ding sme renaming in the new ne OPENGL ES SUPPORT AND EGL A new cpy f the OpenGL driver is available. Nw it is time t change it s that it wrks with OpenGL ES 1.x. This sectin will cver the changes that need t be dne t the driver t use EGL fr thse peratin that are platfrm-dependent such as initializing OpenGL ES, finishing using it r swapping buffers Intrductin t EGL OpenGL ES, just as OpenGL, des nt include the functinality f creating its wn rendering surfaces that is, surfaces t which the API can utput the resulting image. Examples f such surfaces are windws- r t manage them. The reasn nt t d s is t remain as platfrm-independent as pssible, letting the native windw system f each OS t perfrm thse tasks. In the case f OpenGL, there are extensins fr the windw systems f the different OS t wrk with it: in Windws there is WGL, in Linux there is GLX, and in MacOS Page 100

101 there is CGL. In the case f OpenGL ES, hwever, an interface called EGL has been created with the purpse f prviding a unique API fr all platfrms (including mbiles, f curse). As in the case f OpenGL ES, the EGL API has been created by the Khrns grup. Its mst recent specificatin is the versin 1.4, available at [79] (hwever, the versin used in the N95 8GB is the versin 1.1). A gd reference ther than the specificatin, which is itself very clear- wuld be [17]. In the fllwing sectins we will see hw t use this API in the OpenGL ES driver Using EGL There are three main actins fr which EGL will be used in the OpenGL ES driver: Driver initializatin, driver finalizatin and buffer swapping. The fllwing lines describe where and hw these actins have t be perfrmed Header files Prir t using EGL r OpenGL ES, the first step is t change the OpenGL headers included in the different files f the driver t use thse f EGL and OpenGL ES. These files are: The OpenGL ES header file. In the case f the PwerVR emulatr fr Windws, this is the file GLES/gl.h. The EGL header file. Again, in the case f the PwerVR emulatr fr Windws, this is the file GLES/egl.h Driver initializatin In rder t start using OpenGL ES, it is necessary t take certain steps t initialize it. These are dne when the OpenGL ES driver is created. We have seen in the previus sectin (Creating a new driver, page 97) that this is dne by the vide::createopenglesdriver() functin. This functins then creates new instance f the OpenGL ES driver class by calling the vide::copenglesdriver() cnstructr. Afterwards, it initializes the driver by calling the vide::copenglesdriver::initdriver() functin. The cnstructr needs n changes but fr setting the crrect debug name with setdebugname("copenglesdriver"). The functin vide::initdriver(), hwever, has t be heavily mdified s that it uses EGL fr initializing the driver. The prcess f initializing OpenGL ES by using EGL can be split int tw main parts: the platfrm-dependent and the platfrm-independent nes. The platfrm-dependent part is just getting the windw handler and the display device cntext. This has t be dne by using the API prvided by the specific platfrm. After ding s, the rest f the initializatin prcess is dne by using EGL, which is platfrm-independent. This divisin is useful, as it allws us t separate bth parts. The platfrm dependent part will be perfrmed by the vide::initdriver() functin itself. Afterwards, it will be Page 101

102 respnsible fr calling a new functin, vide::copenglesdriver::initegl(), which will perfrm the rest f the initializatin. Prviding that, the vide::initdriver() functin is left as fllws: NativeWindw = native windw handler // casted t nativewindw NativeDisplay = native display device cntext // casted t nativedisplay Call vide::initegl() Pseud cde 2. Pseud cde f vide::initdriver() The native windw handler is available thugh a parameter. The display device cntext, in the case f the Windws platfrm, can be btained by GetDC(). Bth NativeWindw and NativeDisplay are meant t be attributes f the COpenGLESDriver class. Their type is nativewindw and nativedisplay, respectively these types are specified by EGL fr this purpse. The functin vide::initegl() functin is respnsible fr ding the fllwing: Obtain EGL display frm the native display If nt pssible, try btaining the default ne If nt pssible, issue an errr and end Initialize EGL Get the best pssible cnfiguratin (1) Obtain a rendering cntext fr the display and the cnfiguratin Create a rendering surface fr the display and the cnfiguratin Bind the display, the surface and the cntext and make them current fr this thread Set up the swap interval depending n if vertical synchrnizatin was requested Initialize the OpenGL ES states t thse expected by the engine (2) Expse the driver data (3) Pseud cde 3. Pseud cde f vide::initdriver() Mst f these peratins are straightfrward when the EGL API is knwn the nes that are nt in bld-. The fllwing peratins are perfrmed by using a single API call: Obtaining the EGL display: It is dne by using eglgetdisplay(). In rder t request the default ne, EGL_DEFAULT_DISPLAY can be passed as parameter. Initializing EGL: It is dne by using eglinitialize(). Creating a cntext: It is dne by using eglcreatecntext(). Creating a drawing surface fr a windw: It is dne by using eglcreatewindwsurface() Binding all the elements and make them current: It is dne by using eglmakecurrent() Page 102

103 Setting the swap interval: It is dne by using eglswapinterval(). In the case wanting vertical synchrnizatin, the swap interval has t be ne which means that an entire frame have t be rendered between buffer swaps-. If vertical synchrnizatin is nt requested, a value f zer must be used. Other peratin that is quite easy t perfrm is t initialize the OpenGL ES states (2), as this task is perfrmed by anther functin already defined in the driver althugh it will be changed in the next sectin t wrk with OpenGL ES 1.x-, which is called vide::copenglesdriver::genericdriverinit(). The nly thing that is needed is t call this functin. Easy as well is expsing the driver data, but this requires further explanatin t knw what is being dne. Irrlicht has a public structure defined in its API, called vide::sexpsedvidedata that is meant t stre data specific t the driver and the platfrm such that it can be accessed frm utside the engine. The structure is actually a unin f structures, s depending n the current driver it can have different cmpnents. In additin, data types defined by graphics APIs are nt allwed; therwise the end user wuld need the API SKD in rder t be able t cmpile the structure, and that is nt desirable. The drawback f this rule is that it frces string sme data with a data type that is nt its wn, s reinterpret castings are needed. In rder t exprt the data f the OpenGL ES Driver, a new structure have t be added t the unin; we will call it OpenGLESWin32. The fllwing elements shuld be cmpnents f the structure, and shuld be filled in the step (3): The windw handler. The display device cntext. The EGL display. The EGL drawing surface. The EGL rendering cntext. The type s32 is suggested fr all f them but fr the surface and the cntext, where vid * shuld be used -as they are pinters in the Win32 implementatin, as can be seen in the file EGLTypes.h f the PwerVR OpenGL ES 1.x SDK, which we are targeting-. Nte that the EGL display is already stred as an integer, s n reinterpret_cast is need indeed, it will nt cmpile if used-. Finally, the step (1) has t be explained int greater detail, as it is the mst cmplex ne. Different OpenGL ES implementatins can ffer different pssible cnfiguratins fr each pssible display, s chsing the mst apprpriate is needed. In ur case, a new functin, vide::copenglesdriver::getpreferredcnfig(), will be respnsible fr chsing it, given a preferred clr depth in bits-, and whether stencil buffer r antialiasing supprt is requested. The algrithm used fr ding this is: Get all the cnfiguratins available fr the current display and a windw surface Page 103

104 If nne available, return false Fr each f them If its cnfiguratin caveat is EGL_SLOW_CONFIG, discard it Assign a fitness value t each f them // Depth buffer size If the clr depth is greater r equal t 32: +80 If the clr depth is greater r equal t 16: +70 If the clr depth is greater r equal t 8: +60 Otherwise: 0 // Stencil buffer supprt If stencil buffer supprt was requested If the stencil depth is greater than r equal t 8 bits: +50 If it is greater than zer: +40 Otherwise: 0 // Clr depth If the clr depth is the requested: +30 If the clr depth is 32: +20 If the clr depth is 16: +10 Otherwise: 0 // Antialiasing supprt If antialiasing was requested If the value is greater than r equal t 4x: +20 If the value is greater than 2x: +10 Otherwise: 0 Chse the cnfiguratin with the best fitness If nne was gd enugh (best fitness < 0) return false If the cnfiguratin has antialiasing, set the apprpriate attribute t true If the cnfiguratin has stencil buffer supprt, set the apprpriate attribute t true If the cnfiguratin has a clr depth f 16, set the apprpriate texture flag Pseud cde 4. Algrithm fr chsing the best cnfiguratin, implemented in getpreferredcnfig. The first step is t get all the cnfiguratins referred t a windw surface. In rder t d s, eglchsecnfigs() can be used. It is imprtant t enfrce that nly cnfiguratins whse surface type is windw are returned, s n cnfiguratins available fr ff-screen Page 104

105 rendering nly are cnsidered. This is dne by calling the functin with the fllwing data as its attributes parameter: cnst EGLint attributelist[] = { EGL_SURFACE_TYPE, EGL_WINDOW_BIT, EGL_NONE }; After the cnfiguratins have been retrieved, they have t be evaluated ne by ne. The first thing t check is the caveat f the cnfiguratin. A cnfiguratin can have n caveat, can have a slw cnfiguratin caveat, r a nn-cnfrmant caveat. The first ne is the ptimal, the secnd ne means that using the cnfiguratin leads t slw perfrmance fr example, because it is nt fully supprted by the hardware- and the last ne means that using the cnfiguratin yields results nt cnfrmant with the OpenGL ES specificatin. As perfrmance is critical in a real time graphics engine, using a slw cnfiguratin is nt admissible. Because f that reasn, cnfiguratins with that caveat are discarded withut further analysis. Afterwards, it is time t calculate the fitness f each cnfiguratin. The value that each pssibility adds t the fitness f a cnfiguratin has been chsen accrding t the imprtance f each attribute, which is: Depth buffer size. It is the mst imprtant attributes, as it determines the accuracy f the depth tests. When these tests yields errneus results, bjects that shuld be ccluded by ther nes are shwn, being this very nticeable. The greater the value f this attribute, the better. Stencil buffer supprt. The stencil buffer size is the secnd mst imprtant attribute. It determines the accuracy f the shadws f the scene, having thus a very nticeable effect, als. Again, the greater its value is, the better. Clr depth. The clr depth is the next mst imprtant attribute, as the accuracy f the clrs shwn depends n it. Its effect can be seen mstly when there are smth clr transitins. Antialiasing. Antialiasing can be used t vid aliasing as its name suggest-. Aliasing happens when an image f ptentially infinite detail is represented which a limited reslutin. The effect f antialiasing is very nticeable, almst as much as the clr depth. Because f this reasn, bth are cnsidered t have the same imprtance. Prviding this criterin, the fitness assciated with the wrse value f an attribute is still better than the sum f the better values f the attributes that are less imprtant that it. Als, better values have t have greater fitness than wrse values. This rule leads t the fitness values depicted in the Pseud cde 4. Algrithm fr chsing the best cnfiguratin, implemented in getpreferredcnfig. Nte that this criterin is abslutely subjective, but Irrlicht des nt prvide any means t prvide a user-defined ne. Page 105

106 Obtaining the value f a certain attribute can be dne by using the eglgetcnfigattrib() functin. The clr depth is retrieved by passing the EGL_BUFFER_SIZE parameter, the depth buffer size by passing EGL_DEPTH_SIZE, the stencil buffer size by passing EGL_STENCIL_SIZE, and the samples per pixel available fr antialiasing by passing EGL_SAMPLES. It is very imprtant t have the depth buffer size int accunt, because accrding t the rdering defined in the Depending n the chsen cnfiguratin, certain infrmatin has t be prvided t the driver s that it behaves crrectly in the future. If stencil buffer supprt is prvided, the StencilBuffer attribute has t be set t true r t false, therwise-. If antialiasing supprt is prvided, the attribute that has t be set t true is called AntiAlias. Finally, it is advisable t set the ETCF_ALWAYS_16_BIT texture creatin flag if the clr depth is 16 bit. This way, textures will be created with a clr depth f 16 bits, s that they will have the same quality that can be displayed while requiring half the strage f their 32 bits equivalents. The functin vide::copenglestexture::settexturecreatinflag() can be used t set the flag Driver finalizatin Anther part f the driver that needs changes is the driver finalizatin, which is the sequence f peratins that shuld be dne prir t destrying the OpenGL ES driver class (vide::copenglesdriver). As always in C++, these peratins are dne in the destructr f the class (vide::copenglesdriver::~copenglesdriver(), which can be fund in surce/copenglesdriver.cpp). The fllwing peratins have t be dne there: Delete the material renderers Delete the textures. Unbind the OpenGL ES surface and cntext frm the display Release the EGL display Release the Device cntext Pseud cde 5. Operatins needed when finalizing the OpenGL ES driver. The first tw steps are dne just as in the OpenGL driver. Unbinding the OpenGL cntext is dne by using the EGL eglmakecurrent functin(), passing the current EGL display as display and EGL_NO_SURFACE and EGL_NO_CONTEXT as surface and cntext. This is required in rder t be able t release the EGL display aftwards, by using the egltermintate() funtin. Finally, releasing the device cntext is platfrm dependent; in Windws, the WIN32 API prvides the ReleaseDC() functin fr it Buffer swap The peratins f OpenGL r any ther API- that prduce a graphical result utput it t a buffer. In cases when the API is used t create images that shuld be shwn n the screen, if this buffer were the ne used by the hardware t draw the pixels n the screen, mre ften Page 106

107 than nt wrk still in prgress wuld be drawn. T avid this, tw buffers are used at least. Smetimes three buffers are shwn fr ther reasns-. One buffer is the primary ne -als called frnt buffer-, which is used by the graphics hardware t btain the data that has t be drawn n the screen. The ther ne, the secndary buffer -als called back buffer-, is the ne in which the graphics API utputs the results f its peratins. Prviding that, whenever an scene has been cmpletely prcessed by the OpenGL API resulting in a frame that is lcated in the secnd buffer-, a buffer swap has t be dne s that it is shwn n the screen. The methd called whenever a scene has been cmpletely prcessed is r, mre exactly, cmpletely sent t the graphics API- the vide::copenglesdriver::endscene() methd. In rder t ask EGL t d this buffer swap there, the eglswapbuffer() functin shuld be called CORE FUNCTIONALITY Nw that we have mdified the driver t use EGL and ready t use OpenGL ES 1.x, we will start t vercme the changes between this API and the riginal ne. First, we will change the cde that uses cre functinality f OpenGL that is n lnger supprted in OpenGL ES 1.x. After ding this, in further sectins, we will change the cde that uses extensins Simple changes Sme changes required t adapt the OpenGL instructins t OpenGL ES are quite simple. This is the case f the fllwing nes: glclipdepth(). The glcleardepth() functin has nw been replaced by tw different variants: glcleardepthf() that takes a flating-pint number- and glcleardepthx() that takes a fixed-pint number-. Due t this reasn, the call t glcleardepth() in vide::copenglesdriver::genericdriverinit() has t be changed t a call t glcleardepthf(). glclipplane(). The glclipplane() functin has als been replaced by fixed-pint and flating-pint variants, called glclipplanex and glclipplanef() respectively. Thus, it is necessary t replace the call t glclipplane() in vide::copenglesdriver::upladclipplane() with a call t glclipplanef(). Duble data type. In the same methd, an array f duble is used t stre the user clip plane and pass it t the glclipplane() functin. OpenGL ES des nt supprt duble, and an array f flat has t be used instead. Missing errr value. In vide::copenglesdriver::testgl(), a macr called GL_TABLE_TO_LARGE is used as a pssible OpenGL errr. This errr cannt be returned by OpenGL ES, and s that macr is nt defined. The branch f the switch blck it is int has t be remved Lack f supprt fr glbegin glend blcks There are tw main methds f specifying vertex data in OpenGL. The first ne is t use glbegin() glend() blcks, in which the vertex data f a OpenGL primitive can be specified by using the glvertex(), glclr(), glindex(), glnrmal(), gltexcrd(), glevalcrd(), glevalpint(), glarrayelement(), glmaterial() and gledgeflag() cmmands. This methd has the prblem that a single Page 107

108 functin call sets a single datum. Fr example, in rder t specify the psitin f three vertices, three calls t glvertex() are required. This is nt a prblem fr small amunts f data, but it is if many vertices have t be drawn. T avid this, a new way f specifying data was made available frm OpenGL 1.1 n, the usage f the s-called vertex arrays. This methd invlves creating arrays fr string the data f many vertices, and then sending the entire arrays with single functin calls. This way, functin call verhead is greatly reduced, and what is mre, it allws fr ther kind f ptimizatins such as vertex reuse that OpenGL implementatins culd use. In rder t use a vertex array, the fllwing sequence f cmmands is usually emplyed. Create an array fr string the psitins (size= number f vertices x dimensins) Filling the arrays with the psitins sequentially Enable using the array with glenableclientstate(gl_vertex_array) Draw the data by calling gldrawelements() r gldrawarrays() Disable using the array with gldisableclientstate(gl_vertex_array) Pseud cde 6. Hw t use vertex arrays. In the previus example, nly vertex psitins are specified, but different arrays can be als be used nrmal vectrs, texture crdinates and clrs, just by creating the arrays and enabling and disabling GL_NORMAL_ARRAY, GL_TEXTURE_COORD_ARRAY and GL_COLOR_ARRAY instead f GL_VERTEX_ARRAY. Als, it is wrth highlighting that the different between gldrawelements() and gldrawarrays() is that the latter can be used with indexed plygns t maximize even further the reuse f vertex data. Being this last methd f specifying data s pwerful, the glbegin glend blcks where drpped frm the OpenGL ES specificatin, thus being unavailable in the embedded API. Prviding that, every place in the engine that uses the glbegin glend blck methd has t be replaced by the equivalent vertex arrays methd. Such blcks are used in: vide::copenglesdriver::draw2dimage (, cnst cre::psitin2d<s32> ps &, ) vide::copenglesdriver::draw2dimage (, cnst cre::rect<s32> &, ) vide::copenglesdriver::draw2drectangle( cnst cre::psitin<32>&, ) vide::copenglesdriver::draw2dline() vide::copenglesdriver::drawstencilshadw() vide::copenglesdriver::draw3dline() All f them defined in surce/copenglesdriver.cpp Missing gemetric primitives A gemetric primitive is an atmic gemetric element that a graphics API can handle that is, they can be transfrmed, textured, lighted, drawn, etc-. Every element is drawn by OpenGL by using primitives and cmbinatins f primitives. Page 108

109 OpenGL supprts ten different types f primitives, as shwn in the fllwing illustratin. Hwever, OpenGL ES lacks supprt fr sme f them cncretely, the nes pinted ut in the same illustratin. Illustratin 22. OpenGL gemetric primitives. The lack f these primitives has t be cped with in the driver, by using the available primitives t emulate them. The fllwing table shws the equivalences. OpenGL primitives Equivalence with OpenGL ES primitives Table 11. Hw t draw data specified with OpenGL primitives that are unavailable in OpenGL ES. The blue arrws specify the winding f the plygn winding. Page 109

110 As it can be seen, GL_TRIANGLE_STRIP and GL_TRIANGLE_FAN can be used instead f GL_QUAD_STRIP and GL_POLYGON t draw the same data. There is, hwever, n single primitive able t d the same with GL_QUADS; the nly way t emulate it is t use a different GL_TRIANGLE_FAN fr each quad. This is nt a prblem at all, but means that mre functin calls are required, which affects perfrmance. It is als very imprtant t nte that the plygn winding f bth the data drawn with the OpenGL primitives and the OpenGL ES nes has t be the same, s that face culling, fr example, affects the same way t bth. Data using the unavailable primitives is sent t the API in the fllwing methds f the driver: vide::copenglesdriver::drawvertexprimitivelist() vide::copenglesdriver::draw2dimage (, cnst cre::psitin2d<s32> ps &, ) vide::copenglesdriver::draw2dimage (, cnst cre::rect<s32> &, ) vide::copenglesdriver::draw2drectangle( cnst cre::rect<32>&, ) vide::copenglesdriver::drawstencilshadw() All f them defined in surce/copenglesdriver.cpp. Changing them s that the available primitives are used as specified in the table is needed Missing glrec functin The glrect() functin family glrectf(), glrects(), etc- f OpenGL can be used t draw 2D rectangles specified by their upper-left and bttm-right crdinates. This is basically the same as drawing a quad, s using a GL_TRIANGLE_FAN primitive as shwn abve wuld wrk perfectly. Hwever, since this functin is nly called in the methd vide::copenglesdriver::draw2dimage (, cnst cre::psitin2d<s32> ps &, ) which des pretty much the same as the ther methd f the same name but fr the fact that it nly uses a single clr fr the entire rectangle-, it is preferred t adapt it s that it calls the ther ne Plygn mdes As it was said when OpenGL was intrduced, the step in which OpenGL cnverts gemetric data int fragment data part f which will be drawn in the framebuffer and then t the screen as pixels- is called rasterizatin. Depending n the plygn mde set, this step will generate fragments fr vertices nly, brders nly, r fr the entire plygn surface. This prcess is depicted in the fllwing illustratin. Page 110

111 RASTERIZATION +y A triangle strip with fur vertices is specified. Mdel-view transfrmatins and lighting are dne. Perspective prjectin and culling are dne. +x Plygn Mde = POINT VERTEX DATA VERTEX OPERATION PRIMITIVE ASSEMBLY RASTERIZATION +y +y +y +y -z -z -x +z -y -x +z -y +x +x +x Plygn Mde = LINE Depending n the Plygn mde, fragments are created nly fr vertices, fr brders, r fr the entire plygn. These fragments will be later cnverted t pixels, which will be drawn n the screen. RASTERIZATION +y +x Plygn Mde = FILL Illustratin 23. Triangle strip transfrmatins alng part f the gemetry path f the rendering pipeline. It can be seen hw the strip is rasterized depending n the Plygn Mde. These plygn mdes are useful fr drawing graphics as pint cluds r wireframes. Hwever, OpenGL ES des nt supprt any plygn mde different frm GL_FILL, and thus the functin used t change it, glplygnmde(), is nt supprted. Prviding that, the call t this functin dne in vide::copenglesdriver::setbasicrenderstates() shuld be remved. There is still, hwever, a way f prviding supprt fr pint cluds and wireframes in the engine: using GL_POINTS and GL_LINE_LOOP instead f the ther primitives. The next illustratin shws hw this cmpares t using glplygnmde. Page 111

112 VERTEX DATA VERTEX OPERATION PRIMITIVE ASSEMBLY Primitive = GL_POINTS +y +y +y RASTERIZATION +y -z -z -x +z -y +x -x +z -y +x +x +x Plygn Mde = FILL VERTEX DATA VERTEX OPERATION PRIMITIVE ASSEMBLY Primitives = GL_LINE_LOOP RASTERIZATION +y +y +y +y -z -z -x +z -y +x -x +z -y +x +x +x Plygn Mde = FILL VERTEX DATA VERTEX OPERATION PRIMITIVE ASSEMBLY Primitive = GL_TRIANGLE_STRIP RASTERIZATION +y +y +y +y -z -z -x +z -y +x -x +z -y +x +x +x Plygn Mde = FILL Illustratin 24. Hw using GL_POINTS and several GL_LINE_LOOP primitives the same effect as using different Plygn Mdes can be btained. It has t be remarked that GL_POINTS can be used instead f any ther primitive t It shuld be nted that replacing any primitive by the GL_POINTS ne will simulate the GL_POINT plygn mde, but GL_LINES cannt be used in the same way. The fllwing table shws why: Page 112

113 OpenGL primitives GL_LINES using the same vertex data Table 12. Hw the same vertex data is rasterized when using GL_LINES cmpared t the ther plygnal primitives. The nly way t btain a wireframe effect is t use a GL_LINE_LOOP primitive fr each face -triangle, quad r plygn- in the riginal primitive nte that as GL_POLYGON defines a single face, it can be fully replaced by a single GL_LINE_LOOP, as it is made bvius by the table abve. In rder t d s, it is imprtant t knw that: In GL_TRIANGLES, a face is specified every three vertices. In GL_TRIANGLE_STRIP, a face is specified every vertex after the first tw nes. In GL_TRIANGLE_FAN, a face is specified every vertex after the first ne. In GL_QUADS, a face is specified every fur vertices. In GL_QUAD_STRIP, a face is specified every vertex after the first three nes. In GL_POLYGON, a single face is specified. Prviding all this, changes can be dne t vide::copenglesdriver:: drawvertexprimitivelist() as this functin is the ne respnsible fr sending gemetric data t OpenGL ES, as we saw just befre- s that GL_POINTS r GL_LINE_LOOP are used prperly if pint clud r wireframe mde are requested. This can be knwn because in that cases the PintClud r the Wireframe attributes f the current material -stred in vide::copenglesdriver::material- will be true. Page 113

114 Lack f attribute stacks Just as matrices are stred in stacks in OpenGL, s are ther attributes f the OpenGL states. This way, attributes can be easily saved and stred by using the glpushattrib(), glppattrib(), glpushclientattrib(), and glppclientattrib() functins. Hwever, attribute stacks are nt supprted by OpenGL ES, s saving and restring attributes must be dne manually by the applicatin whenever needed. This can be dne by retrieving the attribute value with the crrespnding Get functin see the Chapter 6 f the OpenGL ES specificatin, States and State Queries fr mre detailsand then restring it with the apprpriate cmmands. In the driver, glpushattrib() and glppattrib() are used in the fllwing functins: vide::copenglesdriver::drawstencilshadwvlume() vide::copenglesdriver::drawstencilshadw() This functin calls t glpushattrib() have t be replaced by cde that manually retrieves the values that are changed after its call and glppattrib() is called, and stres them in lcal variables. Then, the calls t glppattrib() have t be replaced by cde that set the attributes t the values stred in that variables. The fllwing table shws hw t save and restre the attributes that are mdified in the glpushattrib() glppattrib() blcks f thse functins, specifying in which ne each attribute is mdified. Page 114

115 Value Data type Hw t get it Hw t set it Func. GL_LIGHTING GLblean glisenabled glenable / B gldisable GL_FOG GLblean glisenabled glenable / B gldisable GL_STENCIL_TEST GLblean glisenabled glenable / B gldisable GL_CULL_FACE GLblean glisenabled glenable / 1 gldisable GL_DEPTH_WRITE_MASK GLblean glgetbleanv gldepthmask B GL_COLOR_WRITE_MASK GLblean[4] glgetbleanv glclrmask B GL_DEPTH_FUNC GLint glgetintegerv gldepthfunc B GL_STENCIL_FUNC GLint glgetintegerv B glstencilfunc GL_STENCIL_REF GLint glgetintegerv B GL_STENCIL_VALUE_MASK GLint glgetintegerv B GL_STENCIL_FAIL GLint glgetintegerv B glstencilop GL_STENCIL_PASSH_DEPTH_FAIL GLint glgetintegerv B GL_STENCIL_PASSH_DEPTH_PASS GLint glgetintegerv B GL_CULL_FACE_MODE GLint glgetintegerv glcullface 1 GL_BLEND GLblean glisenabled glenable / 2 gldisable GL_SHADE_MODEL GLint glgetintegerv glshademdel 2 GL_FRONT_FACE GLint glgetintegerv glfrntface 2 GL_BLEND_SRC GLint glgetintegerv 2 glblendfunc GL_BLEND_DST GLint glgetintegerv 2 Table 13. Values changed within glpushattrib()...glppattrib() blcks in the driver. The Func clumn shws 1 fr values changed in drawstencilshadwvlume(), 2 fr values changed in drawstencilshadw(), and B fr values changed in bth. Nte that values that share a single cell fr the Hw t set it clumn can be set altgether in a single call t the mentined functin Missing texture wrapping mdes In rder t understand what the texture wrapping mdes are, it is imprtant t remember hw texture mapping is dne in OpenGL. First, a texture is laded int OpenGL. Then, parametric texture crdinates are assigned t vertices, as can be seen in the fllwing illustratin. Page 115

116 t 0,1 TEXTURE SPACE a 1,1 OBJECT SPACE A (s,t)=(0.2, 0.8) c b 1,0 s B (0.4, 0.2) C (0.8, 0.4) Illustratin 25. Hw crdinates are used in texture mapping. Illustratin created by Edward Angel. With this data, OpenGL can map the texture t the bject at the rasterizatin stage f the pipeline by using interplatin t calculate which texel texture element - crrespnd t which fragment. When ding s, tw phenmenns can happen: that a single texel cvers several fragments, r that several texels cvers a single fragment. In the first case, the texel will be mapped t thse fragments a prcess called magnificatin-, and in the secnd ne, several texels will be mapped t ne single fragment a prcess called minificatin-. There are tw ways f handle them 58 : by using the nearest texel filter als called pint sampling- r the linear interplatin filter smetimes referred t as bilinear-. Pint sampling chses the texel that is clsest t the (s,t) crdinates and uses it in the mapping. Linear interplatin, hwever, perfrms a linear interplatin between the texels f the 2x2x2 matrix that is clsest t the crdinates and uses that value in the mapping. As linear requires a matrix f 2x2x2 texels depending n the dimensin f the texture, ne r tw dimensins are ignred- fr calculating the value t assign t each fragment, there is a prblem when s r t equals 0 r 1. In the edges f the texture, it wuld be impssible t btain such a matrix, as can be seen in the fllwing illustratin. 58 Actually, there are tw ways in the case f magnificatin, but six in the case f minificatin. The fur extra algrithms available fr minificatin are just different cmbinatins f the nearest texel and linear interplatin filters in cnjunctin with mipmapping. Page 116

117 t?? s Illustratin 26. Lack f data t interplate when t r s are clse t 0 r 1. T slve this prblem, the cncept f texture brder arises. A texture can have 2 texels mre f width and height that is, ne pixel mre n each side f the texture- and use the extrardinary texels at the very edges as a texture brder, which means that their texture crdinates are just utside the [0,1] range. In textures that prvide n brder, a fixed clr is used as such if needed. Nte that texture brders are nly taken int accunt when the linear interplatin filter is used. Other pssible situatin wuld be that a vertex is prvided texture crdinates that are utside the [0, 1] range. What wrapping mdes d is t specify what t d in this situatin. In OpenGL frm 1.5 nwards- there are five different wrapping mdes. The fllwing table shws the result f using them in cmbinatin with linear interplatin filtering. Wrapping mde Descriptin Example CLAMP The crdinates are clamped t the range [0, 1]. CLAMP_TO_EDGE Clamps the texture crdinates such that the texture filter never samples a brder texel. CLAMP_TO_BORDER Clamps the texture crdinates such that the texture filter always samples brder texels fr fragments whse crrespnding texture crdinate is sufficiently far utside the range [0, 1] Page 117

118 REPEAT Ignres the integer part f the texture crdinates, using nly the ratinal part. This way, the texture is repeated alng the crdinate directin. MIRRORED_REPEAT Only the ratinal part f the texture crdinates is used fr indexing. Hwever, that crdinate is mirrred if the integer part is dd. This way, a different texture pattern is btained. Table 14. Different wrapping mdes. Fr the example, a quad with the fllwing texture crdinates was used -frm tp-left in cunter-clckwise directin: (0,2), (0,0), (2,0), (2,2). The glbal texture brder clr was set t pure green -RGBA cmpnents equals t (0,1,0,1)-. Only tw f these wrapping mdes are supprted by OpenGL ES 1.x -as f the 1.1 versin: the CLAMP_TO_EDGE and the REPEAT mdes. The MIRRORED_REPEAT mde is supprted as an extensin. Because f this reasn, the vide::copenglesdriver::setbasicrenderstates() functin has t be changed nt t use the unsupprted mdes. As there is n way f mimicking the behavir f the missing mdes, it is recmmended t replace the usage f GL_CLAMP and GL_CLAMP_TO_BORDER with GL_CLAMP_TO_EDGE, and t left GL_MIRRORED_REPEAT unchanged -it will be dealt with later n, when the driver will be changed t supprt the available OpenGL ES extensins Lack f supprt fr autmatic texture crdinates generatin Smetime, instead f using predefined texture crdinates fr each vertex, it might be useful t have OpenGL generate them based n a certain functin. This is useful, fr example, fr simulating reflectins with an envirnment texture, as the texture has t be mapped differently depending n the vertex psitin and its angle t the viewer. In rder t d s, OpenGL prvides the gltexgen cmmand, which can be used t indicate t OpenGL hw the texture crdinates fr the fllwing vertices have t be generated. There are five different functins that might be used t calculate the texture crdinates. Which ne is used depend n the value f the GL_TEXTURE_GEN_MODE value, which is set using this cmmand. The available mdes are: GL_OBJECT_LINEAR. The texture crdinate is calculated as a linear cmbinatin f the vertex bject crdinates. As bject crdinates are used, the texture is fixed t the bject even if it is transfrmed. GL_EYE_LINEAR. The texture crdinate is calculated as a linear cmbinatin f the vertex eye crdinates. As eye crdinates are used, the texture is nt fixed t the bject and it appears t be in the same psitin even if the bject is transfrmed. Page 118

119 GL_SPHERE_MAP. The texture crdinate is calculated based n the directin in which a ray frm the eye rigin t the vertex wuld bunce. This way, an sphere map can be used t simulate a reflective surface. GL_REFLECTION_MAP. This is pretty similar t the previus ne, but t be used with a cube maps instead f a sphere map. GL_NORMAL_MAP. The texture crdinate is calculated as a cmpnent f the nrmal vectr f the vertex expressed in eye crdinates. The OpenGL driver uses sphere maps fr rendering sme materials. As they are nt supprted by OpenGL ES 1.x as f the 1.1 versin, and there is n replacement fr them, the lines that uses gltexgen and thse that enable autmatic texture generatin with glenable has t be remved. Remving the material types that uses that instructins is nt recmmended, as every driver is expected t have all f them. What fllws is a table that specifies which materials uses sphere maps. Fr each material, its identifier in the vide::e_material_type enumeratin which is lcated in the file include/ematerialtypes.h- and its Material Renderer class which is lcated in surce/copenglesmaterialrenderer.h- are prvided. Identifier Material Renderer class EMT_SPHERE_MAP COpenGLESMaterialRenderer_SPHERE_MAP EMT_REFLECTION_2_LAYER COpenGLESMaterialRenderer_ REFLECTION_2_LAYER EMT_TRANSPARENT_REFLECTION_2_LAYER COpenGLESMaterialRenderer_ TRANSPARENT_REFLECTION_2_LAYER Table 15. Materials that use autmatic texture crdinate generatin Lack f supprt fr certain light mdels In the sectin entitled Lights (page 15), we explained the cmpnents f the Blinn- Phng shading mdel. Bth Direct3D and OpenGL use this mdel fr calculating the lighting f each vertex, and they then interplate by using Guraud shading fr btaining the lighting value f the rest f the surface. The Blinn-Phng mdel prpses the fllwing lighting equatin, which is the frmula that results in the lighting clr cmpnent f a given pint in a surface: Where: I p : Intensity f the light fr the pint p. k s : specular reflectin cnstant, the rati f reflectin f the specular term f incming light k d : diffuse reflectin cnstant, the rati f reflectin f the diffuse term f incming light (als called the Lambertian reflectance cmpnent) Page 119

120 k a : ambient reflectin cnstant, the rati f reflectin f the ambient term present in all pints in the scene rendered α: is a shininess cnstant fr this material, which decides hw "evenly" light is reflected frm a shiny spt, and is very large fr mst surfaces, n the rder f 50, getting larger the mre mirrr-like they are. And the vectrs invlved are: N, nrmal vectr f the surface in the pint p. L, nrmalized vectr in the directin frm p t the light surce R, nrmalized vectr in the symmetric directin f L with respect t the nrmal. V, nrmalized vectr in directin frm the pint p t the viewer. H, a nrmalized vectr in directin f (V+L)/2. It is usually called the halfway vectr. They can all be seen in the fllwing illustratin: Illustratin 27. Vectrs invlved in the Blinn-Phng shading mdel. Taken frm the Wikipedia article abut this shading mdel 59. Certain assumptins can be made in rder t reduce the cmplexity f calculating this equatin. Fr example, assuming that the viewer and the light is at an infinite distance, it is pssible t calculate the H vectr just nce per light, as it becmes independent frm the pint p and the nrmal f the surface in that pint. This gain in perfrmance cmes with a nticeable lst in realism, and s it is pssible t specify that a lcal viewer must be used by setting GL_LIGHT_MODEL_LOCAL_VIEWER t true via the gllightmdeli() functin. Disgracefully, OpenGL ES has n supprt fr this, but Irrlicht uses it. As there is nt a feasible alternative, the nly thing we can d is t remve the call t gllightmdeli() fr this purpse that is made in COpenGLESDriver.cpp. Mre infrmatin abut the lighting in OpenGL can be fund in [80] EXTENSION HANDLING One f the mst acclaimed features f OpenGL is its ability t be extended by anyne by using the s-called extensins. These extensins may and may nt be present in different OpenGL implementatins, s an applicatin meant t run in several f them have t handle 59 Page 120

121 this issue. This is the case f the Irrlicht engine. One f the elements f the OpenGL driver is an Extensin Handler, which is respnsible fr prviding methds t check which extensins are available as well as prviding accesses t the functins defined in them. The extensins supprted by OpenGL and OpenGL ES are quite different. Sme f the features that might be accessed via extensins in OpenGL are cre functinally in OpenGL ES that cannt be accessed the same way; sme ther features are nt available at all. Because f this reasn, a new Extensin Handler will be created fr the OpenGL ES 1.x driver, and several changes will have t be dne t the entire driver s that the required functinality is accessed prperly in all situatins Intrductin t extensins Each release f the OpenGL API cntains a set f cre features that must be supprted by every implementatin f the API. Hwever, implementers are free t extend the functinality prvided by using ptinal extensins. In the future, if thse extensins are prved t be useful and widely-accepted, they can cnverted int ARB-apprved extensins, and then prmted t cre extensins in a future OpenGL release, thus becming cmpulsry. An OpenGL extensin can add new tkens implementatin dependent values, new values fr functin parameters- and new functins t the cre API. Each extensin is identified by a unique string name. Implementers shuld include this string name inside the GL_EXTENSIONS string. This way, OpenGL prvides a simple way f checking the availability f an extensin at runtime by using its string name. All that have t be dne is t retrieve the GL_EXTENSIONS string which can be dne by using a functin f the cre API- and check whether that string cntains the extensin name string inside. If s, the extensin is supprted. Applicatins that are meant t be crss-platfrm shuld als check which extensins are available at cmpile time. This can be dne by using macrs that are defined in the header file f the OpenGL implementatin f the platfrm where the cde is being cmpiled. As an alternative, a header file cntaining the data needed by every registered extensin can be fund in the Khrns OpenGL Extensin Registry 60. OpenGL ES has the same extensin mechanism as OpenGL. The nly difference between the tw is that OpenGL ES supprt has a different extensin registry as it is a different API- and extensins f OpenGL are nt cmpatible with OpenGL ES and vice versa unless registered in bth registries separately The extensin handler The part f the Irrlicht engine in charge f managing extensins is the extensin handler. In ur case, it is the irr::vide::copenglesextensinhandler class, which can be fund in the files surce/copenglesxtensinhandler.h and surce/copenglesxtensinhandler.cpp. 60 Page 121

122 The extensin hander is cmpsed f the fllwing elements: Outside the class. Header includes. Array cntaining the name strings f the extensins. Inside the irr::vide::copenglesextensinhandler class. Public Extensin enumeratin. Cnstructr. initextensins(). queryfeature(). dump(). Blean attributes fr expsing extensins. Attributes fr implementatin-dependant values. Wrapper functins fr extensins. Prtected Functin pinters. Blean array fr extensins. In rder t create a new extensin handler fr the OpenGL ES driver, it is imprtant t knw which extensins may be used by the driver, as this is different in OpenGL and OpenGL ES. The fllwing table shws all the extensins that the OpenGL driver is able and where that functinality can be btained frm in OpenGL ES. OpenGL extensin Equivalence in OpenGL ES 1.x GL_ARB_fragment_prgram Nt available GL_ARB_mirrred_repeat GL_OES_mirrred_repeat GL_ARB_multisample Cre functinality GL_ARB_multitexture Cre functinality GL_ARB_pint_sprite Cre functinality GL_ARB_shading_language_100 Nt available GL_ARB_texture_brder_clamp Nt available GL_ARB_texture_env_cmbine Cre functinality GL_ARB_texture_nn_pwer_f_tw Nt available GL_ARB_vertex_prgram Nt available GL_EXT_fg_crd Nt avaiable GL_EXT_framebuffer_bject GL_OES_framebuffer_bject GL_EXT_packed_depth_stencil GL_OES_packed_depth_stencil 61 GL_EXT_sperate_specular_clr Nt available GL_EXT_stencil_tw_side Nt available GL_EXT_texture_env_cmbine Cre functinality GL_EXT_texture_filter_anistrpic GL_EXT_texture_filter_anistrpic GL_IBM_mirrred_repeat GL_OES_mirrred_repeat 61 This extensin is available at the Khrns OpenGL ES registry, but there is n supprt fr it in the extensins header file fr OpenGL ES. Page 122

123 GL_NV_depth_clamp Nt available GL_SGIS_texture_brder_clamp Nt available GL_SGIS_texture_edge_clamp Cre functinality Table 16. Equivalence between the OpenGL extensins used by the OpenGL driver in Irrlicht and the way f btaining the same functinality in OpenGL ES 1.x. The fllwing lines will explain the differences between the OpenGL Extensin Handler prvides with Irrlicht and a new Extensin Handler fr OpenGL ES 1.x. The changes will be explained element by element, s that it is easier t fllw them Header includes The Extensin Handler needs sme definitins frm ther header files. The headers that need t be included in the OpenGL ES Extensin Handler are: EDriverFeatures.h: It has the definitin f the enumeratin called irr::vide::e_video_driver_feature, which will be used later. irrtypes.h: It prvides the definitins fr the data type that have t be used t ensure prtability acrss platfrms. s.h: Needed t able t use the lgger. The OpenGL ES header file. In the case f the PwerVR emulatr fr Windws, this is the file GLES/gl.h. The EGL header file. Again, in the case f the PwerVR emulatr fr Windws, this is the file GLES/egl.h. The OpenGL ES extensin header file. This shuld be included in the engine prject, just as the rest f the surce files are. It can be btained frm the Khrns OpenGL ES API Registry 62. It is called glext.h, althugh it shuld be renamed in rder nt t cnflict with the existing OpenGL extensin header file f the same name Array cntaining the name strings f the extensins An array cntaining all the name strings f the OpenGL ES extensins is needed s that the initextensins() functin culd search fr them in the extensins string later t check which extensins are supprted by the implementatin and which nt. A list f extensins fr OpenGL ES can be fund at the Khrns OpenGL ES API Registry. This list, hwever, includes the extensins fr bth OpenGL ES 1.x and OpenGL ES 2.x, s filtering it is needed. The name strings f the extensins based n OpenGL ES 1.x registered in Khrns as f tday September f is: GL_OES_blend_equatin_separate GL_OES_blend_func_separate GL_OES_blend_subtract 62 Page 123

124 GL_OES_byte_crdinates GL_OES_cmpressed_ETC1_RGB8_texture GL_OES_draw_texture GL_OES_extended_matrix_palette GL_OES_fixed_pint GL_OES_framebuffer_bject GL_OES_matrix_get GL_OES_matrix_palette GL_OES_query_matrix GL_OES_single_precisin GL_OES_stencil_wrap GL_OES_texture_cube_map GL_OES_texture_env_crssbar GL_OES_texture_mirrred_repeat GL_OES_EGL_image GL_OES_depth24 GL_OES_depth32 GL_OES_element_index_uint GL_OES_fb_render_mipmap GL_OES_mapbuffer GL_OES_rgb8_rgba8 GL_OES_stencil1 GL_OES_stencil4 GL_OES_stencil8 GL_AMD_cmpressed_3DC_texture GL_AMD_cmpressed_ATC_texture GL_EXT_texture_filter_anistrpic This array will be called COpenGLFeatureStrings fr sme reasn, Irrlicht usually refers extensin as features Extensin enumeratin An enumeratin f the extensins will be useful fr indexing a Blean array that will return true if the extensin is available and false therwise. It is als very imprtant that the elements f the enumeratin are defined in the same rder as the name strings, as it is required by the algrithm using in initextensins() fr initializing that Blean array. We will fllw the same cnventin as in the OpenGL Extensin Handler, s the elements f the enumeratin will be named as the name strings, but replacing the GL_ prefix by IRR_. Fr example, GL_OES_stencil1 will map t IRR_OES_stencil1 in the enumeratin. This enumeratin will be called EOpenGLESFeatures. Page 124

125 The Cnstructr The cnstructr is respnsible fr initializing the attributes f the class t their default values nt the actual nes, which will be set by the initextensins() functin. As we will see, the OpenGL ES extensin handler will have neither functin pinters nr many f the Blean attributes that the OpenGL ne has, s their initializatin can be remved frm the cnstructr initextensins() This functin is respnsible fr initializing the internal data f the Extensin Handler t their actual values. The algrithm used fr ding s is the fllwing. Get the GL_VERSION string Extract the versin and prfile frm it (1) Get the GL_EXTENSIONS string Fr each name string (let its psitin be i) Fr each pssible name string (let its psitin be j) (2) Check if the name strings are the same If s Set true the j-th element f the Blean array (3) Set the Blean attributes (4) Set the implementatin dependant values (5) Pseud cde 7. vide::copenglestexture:: getimagedata(). The algrithm is the same in bth the OpenGL and OpenGL ES extensin handler. Hwever, sme changes must be dne n its implementatin. First, a different prcedure has t be used t parse the GL_VERSION string. Accrding t the OpenGL ES 1.x specificatin, the GL_VERSION string has the fllwing frmat: "OpenGL ES-XX<space> N.M" Where XX is a tw-character prfile identifier, either CM fr the Cmmn prfile r CL fr the Cmmn-List prfile and N.M is the majr and minr versin numbers f the OpenGL ES implementatin, separated by a perid. This is different frm the OpenGL versin string, which is required t have the fllwing frmat: N.M V Page 125

126 Where N.M is the majr and minr versin numbers f the implementatin, and V can be any vendr-specific infrmatin. Due t these differences, the versin string has t be parsed differently in (1). The steps (4) and (5) are als different, as they depend n the actual attributes that need t be set. Mre infrmatin abut them can be fund at the sectins Blean attributes fr expsing extensins (page 126) and Blean array fr extensins (page 127). Finally, the steps (2) and (3) are the reasn why COpenGLFeatureStrings and EOpenGLESFeatures shuld refer t extensins in the same rder queryfeature() The queryfeature() functin is part f the Irrlicht API. Every driver has t implement it s that its supprt fr certain features can be queried frm the utside. The features that can be asked fr are defined in the irr::vide::e_video_driver_feature enumeratin, which can be fund in include/edriverfeatures.h. Sme f the features that depend n extensins in OpenGL are always supprted in OpenGL ES 1.x, while sme thers are nt. The differences between the features supprted by the OpenGL and the OpenGL ES driver are shwn in the fllwing table. Feature (withut the prefix EVDF_) OpenGL (Value, extensin required r cnditin fr being true) OpenGL ES 1.x (Value, extensin required r cnditin fr being true) RENDER_TO_TARGET True True MULTITEXTURE GL_ARB_multitexture True r versin > 1.1 BILINEAR_FILTER True True MIP_MAP True True MIP_MAP_AUTO_UPDATE GL_SGIS_generate_mipmap True STENCIL_BUFFER True if enabled by the user. True if enabled by the user. ARB_VERTEX_PROGRAM_1 GL_ARB_vertex_prgram False ARB_FRAGMENT_PROGRAM_1 G_ARB_fragment_prgram False ARB_GLSL GL_ARB_shading_language_10 False TEXTURE_NPOT GL_texture_nn_pwer_f_tw False FRAMEBUFFER_OBJECT GL_EXT_framebuffer_bject GL_OES_framebuffer_bject Table 17. Features supprted by the OpenGL and OpenGL ES 1.x drivers dump() This functin just shws, fr each pssible extensin, whether it is supprted r nt the by the current OpenGL implementatin. It is exactly the same in the OpenGL and the OpenGL ES extensin handlers Blean attributes fr expsing extensins These attributes are set t true r false depending n whether certain extensins are available r nt, s that ther classes that d nt inherit frm the extensin handler class fr example, the texture handler r the material renderers- are able t check them. Page 126

127 Only attributes representing the availability f thse extensins that the OpenGL ES driver is able t use are required. The OpenGL ES driver can nly use tw OpenGL ES extensins, and thus nly tw attributes f this kind are required: AnistrpyExtensin and StencilBuffer, which are true if the GL_EXT_texture_filter_anistrpic extensin and the stencil buffer are supprted, respectively Wrapper functins fr extensins As it has been previusly said, functins prvided by extensins can be accessed either by using external functin pinters r with cmmn functin calls, if the functin prttypes are prvided. Depending n the value f the _IRR_OPENGL_USE_EXTPOINTER_ macr, Irrlicht will try t use the external pinters first r nt. The extensin handler prvides wrapper functins fr these extensin functins s that the rest f the driver has nt t wrry abut hw t actually access them. Because the OpenGL ES 1.x extensins that the driver will be able t use prvide n functins, n wrapper functins are needed fr them in the extensin handler Functin pinters Generally, nce the availability f an extensin is checked at bth cmpile time and runtime, the functins and tken prvided by it can be used just as the cre nes are in thse platfrms where the OpenGL implementatin is cntained just in a shared library. This is, hwever, nt the case f the Windws platfrm, fr example. In Windws, OpenGL applicatins are linked with an OpenGL shared library prvided by Windws, nt the vendr r the graphics hardware. The OpenGL implementatin f Micrsft, in turn, is respnsible fr calling anther shared library knwn as ICD prvided by the vendr, which is the ne wh des the actual wrk. The prblem with this apprach is that the OpenGL extensins are nly available at the ICD, nt in the library the applicatin is linked with; this means that the OpenGL applicatins cannt access the extensin functins directly. In rder t d s, a platfrm specific functin has t be used, which returns the functin pinter f the requested extensins. Mre infrmatin abut this can be fund at [81]. In the case f the OpenGL ES extensin handler n functin pinters are, as nne f the extensins that the driver is able t use prvides any functin Blean array fr extensins This array, called FeatureAvailable, stres a Blean value per each extensin that is true if it is available and false therwise. It is usually addressed by using the members f the EOpenGLESFeatures enumeratin -which is pssible because in C++ the elements f the enumeratins are nthing mre than macrs with integer values-. The nly thing that needs t be changed in this array is its size. Page 127

128 Attributes fr implementatin dependant values There are sme parameters and values that are fixed by the OpenGL ES implementatin and ffer relevant infrmatin. Parameters f this nature are, fr example, the maximum number f lights, the maximum number f texturing units, etc. What is mre, several extensins can als define new parameters that the driver might need t take int accunt. These parameters are btained by the extensin handler and stred in attributes, s that ther parts f the driver can access them withut having t request them t OpenGL again, thus increasing perfrmance and readability. The attributes needed by the OpenGL ES 1.x driver are: MaxTextureUnits. The maximum texture layers supprted by the fixed pipeline. MaxLights. The maximum number f lights supprted by the hardware. MaxIndices. The maximum number f indices that a mesh buffer can stre. MaxAnistrpy. The maximum degree f anistrpy supprted by the hardware. This parameter is intrduced by the GL_EXT_texture_filter_anistrpic extensin. MaxUserClipPlanes. The maximum number f user clip planes supprted by the OpenGL ES implementatin. The fllwing table shws which OpenGL ES parameter stres them and which functin t use t retrieve their value. Attribute f the EH OpenGL attribute name Get cmmand MaxTextureUnits GL_MAX_TEXTURE_UNITS glgetintegerv MaxLights GL_MAX_LIGHTS glgetintegerv MaxIndices GL_MAX_ELEMENTS_INDICES glgetintegerv MaxAnistrpy GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT glgetintegerv MaxUserClipPlanes GL_MAX_CLIP_PLANES glgetintegerv Table 18. Implementatin dependant values used in the OpenGL ES 1.x driver. Mre infrmatin n these values can be fund at [82] and [83] Changes in the driver After creating the new extensin handler, changes in the driver has t be made als s that the OpenGL ES functinality required is accessed prperly. T begin with, the macrs defined by the OpenGL extensins are nt available in the OpenGL ES implementatin, as mst f them have changed their name in the new API. The fllwing table shws the OpenGL macrs used by the OpenGL driver and their equivalent in the OpenGL ES API, which are the nes the OpenGL ES driver needs t use thus, replacing any instance f the OpenGL macrs f this table with its equivalent in the surce cde f the driver is needed. Page 128


130 OpenGL Extensin Handler wrapper functin OpenGL ES equivalent functin GL_ARB_multitexture - nw cre extglactivetexture glactivetexture extglclientactivetexture glclientactivetexture GL_ARB_pint_sprite nw cre extglpintparameterf glpintparameterf extglpintparameterfv glpintparameterfv Table 20. Equivalence between the OpenGL Extensin Handler wrapper functins and the OpenGL ES functins. Alng with replacing macrs and functin calls, there are several extensin availability checks that need t be revised. In fact, checks fr the Blean attributes f the extensin handler that n lnger exist have t be remved, and in the cases where the functinality being access is nt available in the OpenGL ES API, the entire blck f cde using that functinality remved. It is quite easy t d, as the cmpiler will cmplain until this part is cmpletely finished. There are, hwever, tw main functinalities that are prvided by extensins that are used in the OpenGL driver but cannt be used the OpenGL ES ne: shaders and framebuffer bjects. The first ne, the shaders, are nt available since OpenGL ES 1.x uses a fixed pipeline and, thus, they are nly be available in OpenGL ES 2.x which we d nt supprt. As we are nt supprting shaders, we can remve the Renderers used t manage them. They are the NrmalMapRenderer, the ParallaxMapRenderer, the ShaderMaterialRenderer and the SLMaterialRenderer, which are lcated in the files: surce/copenglesnrmalmaprenderer.h surce/copenglesnrmalmaprenderer.cpp surce/copenglesparallaxmaprenderer.h surce/copenglesparallaxmaprenderer.cpp surce/copenglesshadermaterialrenderer.h surce/copenglesshacermaterialrenderer.cpp surce/copenglesslmaterialrenderer.h. Apart frm remving them, the functin in charge f setting which renderers are available, COpenGLESDriver::createMaterialRenderers(), shuld be updated s that it des nt add thse renderers t the driver. In additin, sme methds f the driver that deals with driver shuld be mdified. The methds addshadermaterial() and addhighlevelshadermaterial() and getgpuprgrammingservices() can be safely remved, as they are verride methds f the CNullDriver class frm which every driver inherits- whse default behavir is suitable fr us they just infrm the user f the unavailability f their service. On the ther hand, the functins setvertexshadercnstant(), setpixershadercnstant() cannt be remved as they Page 130

131 are nt prvided a default behavir in an upper class. Instead f ding s, they can be changed s that they just d nthing. Cncerning the frame buffer bjects (FBOs), they are just bjects in which OpenGL can render. Their main advantage is that different buffers can be attached t FBOs s that they are used in the rendering prcess. Fr example, a texture can be attached t a frame buffer bject as a clr buffer, s that the texture will cntain the clr infrmatin resulting frm rendering t the FBO thus achieving a Render-T-Texture functinality-. This is, indeed, the technique fr which Irrlicht uses FBOs. Supprt fr FBOs was intrduced in OpenGL ES 1.1 with the first Extensin Pack. Hwever, Irrlicht uses them in cnjunctin with depth textures, which are nt supprted by the API. Because f this reasn, the OpenGL ES driver cannt use this technique and s frame buffer bject supprt have t be remved frm the driver. Frtunately, Irrlicht is able t render t texture withut FBOs als. In rder t s, the secnd cnstructr f vide::copenglestexture which builds the texture as a frame buffer bject have t be remved, alng with where it is used in the vide::copenglesdriver::createrendertargettexture() methd. The methds isframebufferobject(), bindframebufferobject() and unbindframebufferobject() f the vide::copenglestexture class need als t be changed s that they d nthing. After ding all this, the OpenGL ES driver will wrk crrectly, taking advantage f whichever extensins are available in the OpenGL ES implementatin, and using all thse features that was previusly btained via extensins and that are nw cre in the embedded API COLOR HANDLING One f the biggest prblems when creating the OpenGL ES driver was that mst f the clr frmats used in Irrlicht cannt be read by OpenGL ES. The fllwing lines will explain this prblem in greater detail, which slutins are pssible, which ne was chsen, and hw it has t be implemented The prblem In rder t understand why this happens exactly, certain knwledge abut hw Irrlicht and OpenGL manage clrs is needed. Irrlicht supprt fur different clr frmats: A 1 R 5 G 5 B 5, R 5 G 6 B 5, R 8 G 8 B 8 and A 8 R 8 G 8 B.These names refer t the size and rdering f the clr cmpnents f a given pixel in memry. It is imprtant t clarify that the actual layut f the pixel data in memry depend n Page 131

132 the endianness f the architecture in with the engine is running. The fllwing table shws hw these frmats are stred in memry in little- and big-endian machines 63. Clr frmat Big-endian layut Little-endian layut A 1 R 5 G 5 B st byte A R G nd byte G B R 5 G 6 B st byte R G nd byte G B R 8 G 8 B st byte R nd byte G rd byte B A 8 R 8 G 8 B st byte A nd byte R rd byte G th byte B st byte G B nd byte A R G st byte G B nd byte R G st byte R nd byte G rd byte B st byte B nd byte G rd byte R th byte A Table 21. Memry layuts fr the Irrlicht clr frmats. Nte that the R 8 G 8 B 8 frmat is stred the same way in big- and little-endian machines. This is because Irrlicht accesses data in this frmat at byte level as there is n 24-bit data type in C++- and thus endianness is nt an issue. The different image laders that Irrlicht prvides can use any f these frmats t stre the images in memry. Afterwards, when a texture using a laded image is created, the image is then cpied int the new texture in the same frmat r in a new ne depending n what the driver demands-; hwever, the new frmat wuld still be ne f these. When the texture needs t be shwn n the screen, it shuld be passed t the underlying graphics API; in ur case, OpenGL. In rder t d s, the fllwing OpenGL functin shuld be used: 63 Nte that this is hw the Irrlicht engine wrks. Hwever, it wuld be pssible t stre the data with any desired endianness regardless f the architecture by just managing the memry at byte-level, - i.e. withut using ther data types such as shrt r int. Page 132

133 vid glteximage2d(glenum target, GLint level, GLint internalfrmat, GLsizei width, GLsizei height, GLint brder, GLenum frmat, GLenum type, cnst GLvid * pixels) Where the different parameters are: target: The target texture. Irrlicht uses GL_TEXTURE_2D which is the nly accepted value in OpenGL ES. level: The level f detail. Used with mip-maps. internalfrmat: Used t specify which clr cmpnents are present in the texture and, ptinally in OpenGL, the size that OpenGL shuld use t stre each f them internally. width: width f the texture in texels. height: height f the texture in texels. brder: width f the brder t be used. In Irrlicht zer is used luckily, as it is the nly accepted value in OpenGL ES. frmat: Used t specify which clr cmpnents are present in the texture and in which rder. type: Used t specify the data type f the different clr cmpnents and its layut in memry. pixels: address f the texture in main memry s that OpenGL can access it and cpy it. As it can be seen, three parameters are used t tell OpenGL hw t read the texture data it is prvided: internalfrmat, frmat, and type. The internal frmat is used just t specify which cmpnents are present in the pixel data, as already explained. The frmat supprted by Irrlicht can have nly either RGB r RGBA cmpnents, s these are the values fr this parameter used by the engine. The frmat is used t indicate an rder in thse cmpnents. Fr example, RGBA means that red have t be cnsidered the first cmpnent, green the secnd ne, blue the third and finally alpha the furth. Finally, the type defines the data types that OpenGL must read frm the texture data. Fr example, if the value f this parameter is GL_UNSIGNED_BYTE, OpenGL will read single bytes frm the memry, and each byte will be interpreted as the value f a different clr cmpnent. There are sme special types, called packed pixel frmats, which are used fr specifying that several cmpnents f the pixel are packed inside a single data type. This wuld be the case f GL_UNSIGNED_BYTE_3_3_2, fr example, which indicates that OpenGL Page 133

134 have t read byte by byte, and that inside each byte the first three mst significant bits are the value fr the first cmpnent f a pixel, the next three f the secnd cmpnent, and the tw last f the third. By default, the OpenGL data types are interpreted just as the data types f the prgramming language f the client side prgram. This means that if the prgramming language in which the prgram is being made has little-endian data types, the data types f OpenGL will als be little-endian, and vice versa. This frees the develpers frm wrrying abut endianness when the texture data d have the data type specified. Hwever, it has still t be taken int accunt when this is nt the case. A cmmn example f this is when using three bytes fr string texture data, such as in the R 8 G 8 B 8 frmat. As OpenGL lacks a data type f three bytes f size, it will have t read the texture data byte by byte. Hwever, if the data in memry were in little-endian, the first byte that OpenGL wuld read will crrespnd t the last clr cmpnent, the next ne t the third, and s n. Because f this reasn, instead f using the GL_RGB value fr the frmat parameter, GL_BGR shuld be used instead. This is nt a prblem in Irrlicht, as it always stre data in the R 8 G 8 B 8 frmat in big-endian regardless f the endianness f the platfrm the engine is running n. With the crrect values fr these parameters, OpenGL can be able t read the frmats supprted by Irrlicht. The fllwing table shws which values can be used fr that purpse. Page 134

135 Irrlicht clr frmat Internal frmat frmat type A 1 R 5 G 5 B 5 R, G, B, A GL_BGRA_EXT 1st cmpnent 2nd cmpnent 3rd cmpnent 4th cmpnent R 5 G 6 B 5 R, G, B GL_BGR_EXT 1st cmpnent 2nd cmpnent 3rd cmpnent Blue Green Red Alpha Blue Green Red GL_UNSIGNED_SHORT_1_5_5_5_REV shrt shrt 2 1 GL_UNSIGNED_SHORT_5_6_5_REV shrt shrt 2 1 R 5 G 6 B 5 (ther alternative) R, G, B GL_RGB 1st cmpnent 2nd cmpnent 3rd cmpnent Red Green Blue GL_UNSIGNED_SHORT_5_6_ shrt shrt 2 3 R 8 G 8 B 8 (if stred in bigendian) R, G, B GL_RGB 1st cmpnent 2nd cmpnent 3rd cmpnent Red Green Blue GL_UNSIGNED_BYTE st byte nd byte rd byte 3 A 8 R 8 G 8 B R, G, B, A GL_BGRA_EXT 1st cmpnent 2nd cmpnent 3rd cmpnent 4th cmpnent Blue Green Red Alpha GL_UNSIGNED_INT_8_8_8_8_REV int int Int Int 4 Table 22. OpenGL parameter values that can be used t read the clr frmats supprted by Irrlicht. The prblem arises, hwever, when OpenGL ES 1.x needs t be used instead f OpenGL. OpenGL ES 1.x des nt supprt mst f the types and frmats needed t read the clr frmats used in Irrlicht at least, nt withut extensins-. In fact, the nly pssible frmats are: GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA. Cncerning types, the nly nes supprted are Page 135

136 GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4, and GL_UNSIGNED_SHORT_5_5_5_1. Because f this reasn, OpenGL ES can nly read R 5 G 6 B 5 by using the secnd prpsed alternative- and R 8 G 8 B 8 -as it is always stred in big-endian Pssible slutins The simplest slutin wuld be t let Irrlicht use any f the frmats and, just befre sending it t OpenGL, cnvert the texture data t be sent t R 5 G 6 B 5 r R 8 G 8 B 8 and set the crrect parameters fr OpenGL ES t be able t read that data. This slutin, hwever, has tw main drawbacks. The first ne is that bth f these frmats are unable t carry alpha infrmatin, s it wuld be impssible t render transparencies, which is a really severe limitatin-. The secnd ne is that the cnversin wuld need t be dne every time the texture is sent t OpenGL ES, which might happen several times. What is mre, memry wuld need t be allcated in rder t stre the cnverted texture, s each texture wuld ccupy twice the required memry. Prviding this, new clr frmats shuld be used. The fllwing table shws which new frmats can be used instead f the nes that are nt supprted by OpenGL ES. New clr frmat Internal frmat frmat type R 5 G 5 B 5 A 1 R, G, B, A GL_RGBA 1st cmpnent 2nd cmpnent 3rd cmpnent 4th cmpnent A 8 B 8 G 8 R 8 R, G, B, A GL_RGBA 1st cmpnent 2nd cmpnent 3rd cmpnent 4th cmpnent Red Green Blue Alpha Red Green Blue Alpha GL_UNSIGNED_SHORT_5_5_5_ shrt shrt GL_UNSIGNED_BYTE int int Int Int 1 Table 23. New clr frmats fr Irrlicht, and which parameters t use s that OpenGL ES can read them. 64 The frmat shwn here is the ne depicted in the OpenGL ES 1.x specificatin. Hwever, the PwerVR SDK has a bug regarding this frmat it behaves as GL_UNSIGNED_SHORT_5_5_1_5 wuld- s using the R5G5B5A1 frmat in the PC emulatr will result in incrrect clrs being displayed. Page 136

137 There are three pssible ways f using the new frmats. First, we culd simply substitute the previus ne and update everywhere they were used. This wuld break cmpatibility with the ther drivers, while still requiring quite a lt f wrk. Secnd, we culd just add the new frmats but nly use them cnvert the texture data prir t sending it t OpenGL ES, as prpsed befre. This, hwever, presents the previusly mentined prblem f memry wastage. Finally, the ther pssible slutin is t make the textures t be used by the OpenGL ES device t be created with just ne f the supprted frmats. This requires far mre wrk than the ther ptins, but it is the slutin that wuld ffer the best perfrmance at runtime s it was the chsen ne Implementatin The first step is t add the new frmats t the frmats enumeratin: vide::ecolor_format (lcated in the file include/iimage.h). After ding that, the exact mechanism that is used t create a texture in Irrlicht must be understd in rder t cntinue. When a new texture is being created, the cnstructr f vide::copenglestexture is called (which is lcated in the file surces/copenglestexture.cpp). The cnstructr initializes sme attributes which have n relevance, as they are nt used until later, after their value is prperly assigned-, and, amng ther things, calls vide::copenglestexture::getimagedata() with the image t be used in the texture as parameter. This functin is the ne that actually sets up the texture. The algrithm used by this functin is the fllwing: Get the size f the texture Check whether the OpenGL ES implementatin supprts nn-pwer-f-2 texture sizes. If s Else Set the current size as the size fr the new image Calculate the minimum pwer-f-2 size that can hld the entire texture Get the best frmat t be used by the image cpy f the texture (1) Check whether the size f the new image is the same as the image f the current image If s Else Create new cpy f the image, cnverted t the specified frmat (2) Create a new empty cpy f the image (3) Scale the new image and cnvert it t the specified frmat (3) Pseud cde 8. vide::copenglestexture:: getimagedata(). The mre relevant parts have been highlighted in bld and marked. In (1), a call t the vide::copenglestexture::getbestclrfrmat() functin is made t get which frmat t use fr the new texture. This means that that functin is where the decisin is made. Page 137

138 This functin shuld be changed t return the new frmats instead f the ld nes, which is pretty straight-frward. Then, in (2), a new cpy f the image with the new frmat is created. It is imprtant t find where the cnversin is dne, in rder t update the algrithm s that the required cnversins t the new frmats can be dne. The image with the new frmat is created by the cnstructr f vide::cimage lcated in surces/cimage.cpp). One f the first things it des is t set the bitmasks fr the different cmpnents. This is dne by the vide::cimage::getbitmasks(), which need t be mdified s that it has the new frmats int accunt. The bitmasks fr the new frmats are: Clr R 5 G 5 B 5 A 1 A 8 B 8 G 8 R 8 Alpha 0x0001 0xFF Red 0xF800 0x000000FF Green 0x07C0 0x0000FF00 Blue 0x003E 0x00FF0000 Table 24. Bit masks fr the new clr frmats. The next thing it des is t allcate the memry fr the new image via the vide::cimage::initdata() functin-. In rder t d s, it needs t get hw many bits are needed by the image frmat. This data is meant t be prvided by the vide::cimage::getbitsperpixelfrmfrmat() functin, which must be updated in rder t prvide this infrmatin when asked by the new frmats. After that, the data f the previus image is cnverted t the new frmat and the result is stred in the new image. This is dne by using a blitter. A blitter is a functin that mves data frm a lcatin t anther and is able t perfrm peratins t it. It is mstly used by the sftware driver t perfrm certain raster peratins (such as texturing, alpha blending, etc). Hwever, it is als used fr the purpse f cpying images while cnverting the frmat at the same time. Because f that, in rder t be able t perfrm this peratin applied t the new frmat, we have t prvide new blitters fr cnverting frm the previus frmats t the new nes, and make them available fr use by updating the vide::cimage::blit() functin. In fact, blitters fr cnverting t the R5G6B5 frmat must als be added, as they are missing in the versin f Irrlicht but are required under certain circumstances it is prbably a bug. The new blitters that need t be created are shwn in the fllwing table: Page 138

139 Surce Destinatin Blitter functin frmat frmat A1R5G5B5 R5G5B5A1 executeblit_texturecpy_a1r5g5b5_t_r5g5b5a1() R5G6B5 executeblit_texturecpy_a1r5g5b5_t_r5g6b5() A8B8G8R8 executeblit_texturecpy_a1r5g5b5_t_a8b8g8r8() R5G6B5 R5G5B5A1 executeblit_texturecpy_r5g6b5_t_r5g5b5a1() A8B8G8R8 executeblit_texturecpy_r5g6b5_t_a8b8g8r8() R8G8B8 R5G5B5A1 executeblit_texturecpy_r8g8b8_t_r5g5b5a1() R5G6B5 executeblit_texturecpy_r8g8b8_t_r5g6b5() A8B8G8R8 executeblit_texturecpy_r8g8b8_t_a8b8g8r8() A8R8G8B8 R5G5B5A1 executeblit_texturecpy_a8r8g8b8_t_r5g5b5a1() R5G6B5 executeblit_texturecpy_a8r8g8b8_t_r5g6b5() A8B8G8R8 executeblit_texturecpy_a8r8g8b8_t_a8b8g8r8() Table 25. New blitters t be created s that cnversin t the new frmats are pssible. All these blitters have a similar structure, which is shwn in the fllwing pseud cde. src = jb->src //surce address dst = jb->dst //destinatin address fr dy = 0 t jb->height fr dx = 0 t jb->width destinatin bytes = cnversin functin( surce bytes) src += jb->srcpitch //the size in bytes f a rw f pixels dst += jb->dstpitch Pseud cde 9. Structure f a blitter fr texture cpying. The cnversin functins are meant t receive the byte representatin f a pixel and return the byte representatin f the same pixel in the new frmat. The place t define these functins is the include/sclr.h file, as it is where the already available cnversin functins are which make sense, as the end user have access t the functins defined this lcatin-. As we will need them further n, it is recmmendable t create cnversin functins frm every frmat t every frmat, even althugh the blitters d nt need all f them. Als, this functins are meant t be quick rather than precise, s using just bit peratrs is advisable. A simple general algrithm fr cnverting the clr cmpnent f ne frmat int the clr cmpnent f anther is shwn in the next pseud cde: (( (surce_pixel & surce_frmat_clr_mask) >> surce_frmat_clr_ffset) >> (destinatin_frmat_clr_size - surce_frmat_clr_size) ) << destinatin_frmat_clr_ffset Pseud cde 10. Frmula fr cnverting a clr cmpnent f a clr frmat t the same cmpnent f ther frmat. Page 139

140 Where: Surce_pixel: the pixel value in the riginal frmat [Surce/destinatin]_frmat_clr_mask: the bit mask f a certain clr in the surce r destinatin frmat. Fr example, the mask fr the green clr in A 8 R 8 G 8 B 8 wuld be 0x0000FF00. [Surce/destinatin]_frmat_clr_ffset: the ffset f the clr in the frmat. That is, the first bit f that cmpnent. Fr example, the green cmpnent f the A 8 R 8 G 8 B 8 frmat wuld be 16 as the bits start cunting frm zer-. [Surce/destinatin]_frmat_clr_size: the size f the clr cmpnent in the frmat. In the case f the green in A 8 R 8 G 8 B 8 it wuld be 8. It shuld be nted that in cases where the size f destinatin clr cmpnent is bigger than the size f the surce clr cmpnent, a lgic right shift instead f a left shift as shwn in the pseud cde shuld be used. In rder t cmbine several clr cmpnents in a single pixel the lgical OR peratr can be used. Once the cnversin functins and the blitters are dne, the vide::cimage::blit() functin shuld be mdified s that the cases in which the destinatin frmats are the new nes are cntemplated in its switch statement and the apprpriate blitter functins is returned. The next step is t ensure that scaled cpies are als cnverted crrectly t the new frmats -remember (3) in Pseud cde 1.. Scaled cpies are dne by calling vide::cimage::cpytscaling(). This functin, in turn, uses a class, called vide::cclrcnverted, specialized in cnversins between clr frmats -Why this class was nt used fr cnverting images that d nt need scaling instead f using specificpurpse blitters is unknwn t us, we have just fllwed the established cnventin-. The mst imprtant methd f this class is vide::cclrcnverted:: cnvert_viafrmat(). This methd is just a dispatcher that applies the prper cnversin functin fr the given surce and destinatin frmats fr which it is called. In rder t update this functin t take int accunt the new frmats, we need t add them t the switch statement it uses and t prvide the specific cnversin functins called smething like vide::cclrcnverter::cnvert_srcformattdestformat()-. Nte that these cnversin functins are meant t be applied t blcks f pixel data, nt just a single pixel as the nes we did befre. In fact, this new cnversin functin can be easily design t use the thers just by iterating ver the pixel data and calling them fr each pixel. By this time, Irrlicht is already able t display any diffuse texture crrectly as they can be created, scaling them if needed, and read by the OpenGL ES driver-. There are, hwever, mre peratins that can be dne t OpenGL ES textures that need t supprt the new frmats. One f thse functins is mipmap creatin. Mipmaps are smaller versins f textures that can be used t reduce the number f pixels that need t be prcessed when rendering Page 140

141 textures frm a certain distance. OpenGL ES can generate the mipmaps autmatically if s requested, but Irrlicht als prvides a functin fr ding s, that is called vide::copenglestexture::regeneratemipmaplevels(). This functin, hwever, needs n mdificatin apart frm what have been already dne, as it uses vide::cimage::cpytscaling(). Anther functin that perates with textures and has t be updated is the vide::cnulldriver::makeclrkeytexture(vide::itexture*texture, vide::sclr clr) functin. It creates an alpha channel based n a clr key. That is, it makes thse pixels f a certain clr invisible. In rder t d s, the fllwing algrithm is used: check if the texture clr frmat is valid if nt, return Get the texture data Calculate reference clr // which is the key clr but with alpha = 1 r 0xFF and // cnverted t the texture new frmat if needed Fr each pixel Calculate cmparable clr // which is the pixel clr but with alpha = 1 r 0xFF If reference clr equals the cmparable clr else set the pixel t zer // making them invisible, as alpha is zer t set the pixel t the cmparable clr // the same as setting alpha = 1 r 0xFF Pseud cde 11. Algrithm fr making an alpha channel based n a clr key. The steps in bld are thse that depend n the clr frmat used in the texture. The versin used in Irrlicht supprts bth A 1 R 5 G 5 B 5 and A 8 R 8 G 8 B 8 ; we have t mdify it s that it als supprts R 5 G 5 B 5 and A 8 B 8 G 8 R 8. In rder t d s, new cnditinal branches shuld be dne and the bitmasks used fr setting the alpha t its maximum value have t be replaced there. It is preferable t duplicate the cde after getting the texture data fr each supprted frmat rather than using cnditinals fr the frmat-dependent cde nly as ding s wuld add a cnditinal instructin per pixel, greatly affecting perfrmance-. Apart frm ding s, the reference clr passed as parameter will be an instance f the vide::sclr class, that stres the clr in A 8 R 8 G 8 B 8 frmat. This means that in rder t create the reference clr, the result f cnverting it t the texture frmat shuld be used, s that cmparisns with it can be made later. In additin, it is imprtant t mdify the clr frmat check at the beginning f the algrithm s that the new frmats are accepted. The vide::cnulldriver::makeclrkeytexture( vide::itexture* texture, cre::psitin2d<s32> clrkeypixelps) functin is a variatin f the abve. Instead f being given a clr as parameter, the psitin f that clr inside the texture is given. Thus, the algrithm is basically the same as abve, but calculating the reference clr Page 141

142 invlves getting it first frm the texture using the given crdinates- and then prceeding as befre. The changes that this functin needs are exactly the same as befre. Other peratin that can be dne t textures is t build a nrmal map frm them. A nrmal map is a special kind f texture that stres nrmal vectrs in tanget space that is, with respect t the surface f the gemetry in which they wuld be applied. This cnversin frm texture t nrmal map is dne in the vide::cnulldriver::makenrmalmaptexture(). The fllwing algrithm is used t perfrm this peratin: check if the texture clr frmat is valid Get the texture data Create a cpy f the texture data fr each pixel f the cpy calculate the hrizntal vectr f the quad it is centered int (1) calculate the vertical vectr f the quad it is centered int (2) crss prduct them t get the quad nrmal nrmalize it apply the amplitude factr t it replace the pixel in the riginal texture with the nrmal (3) Pseud cde 12. Algrithm fr creating a nrmal map frm a height map texture. In rder t understand the steps (1) and (2) better, the fllwing illustratin shws hw thse vectrs are calculated. Illustratin 28. Hw t calculate the nrmal f a pint f a height map. The algrithm fr this calculatin by itself is independent n the clr frmat f the texture, but fr the cde that needs t retrieve the height frm the height map. This height is encded differently depending n the texture frmat, s we have t make it supprt the new nes. Page 142

143 In rder t retrieve the height frm a texture, tw functins are used in Irrlicht 1.4.1, depending n the texture frmat: vide::cnulldriver::nml16() and vide::cnulldriver::nml32()fr A 1 R 5 G 5 B 5 and A 8 R 8 G 8 B 8 respectively. The nml16() functin checks the bundaries f its parameters and calls anther functin, vide::sclr::getaverage() that returns the average f the red, green and blue cmpnents as the height value. Thse cmpnents are retrieved by using the vide::getred(), vide::getgreen() and vide::getblue() functins, that unfrtunately can nly wrk with A 1 R 5 G 5 B 5 clrs. The best way t mdify this is t add an ptinal parameter t these functins s that they can wrk with the new frmats and, being the parameter ptinal, cmpatibility is nt cmprmised-. The same shuld be dne with getaverage(), and finally t nml16(). As include/sclr.h des nt includes include/iimage.h, where the vide::ecolor_format enumeratin with the clr frmats is lcated, but include/iimage.h des include include/sclr.h, changing the lcatin f the numeratin t include/sclr.h is needed. It is nt a prblem, since include/iimage.h wuld still have access t it via its include. Regarding nml32(), it des almst the same, but instead f calling getaverage() t return the average f the clr cmpnents, it directly returns the value f the red cmpnent as the height value. Adding a new ptinal parameter fr the frmat t this functin and using a different mask t retrieve the red cmpnent depending n its value is all that is needed t make the functin wrk with the new frmats. Returning t (1) and (2), they nly have t be mdified s that they call the nml16() and nml32() functins with the crrect frmat parameter. The final step s that nrmal maps can be generated is t mdify the step (3) s that the calculated nrmal vectrs are crrectly stred in the nrmal map. It is imprtant fr the 16-bit frmats that the 5 mst significant bits f each nrmal cmpnent are used; a simple truncatin wuld nt wrk. After ding all this, Irrlicht shuld be able t use the textures fr OpenGL ES withut any prblem in every situatin where driver-specific textures are meant t be used Summary Add the new frmats t the vide::ecolor_format enumeratin. Update vide::copenglestexture::getbestclrfrmat() t return the new frmats. Update vide::cimage::getbitmasks(). Update vide::cimage::getbitsperpixelfrmfrmat(). Create new cnversin functins that cnvert pixels in previus frmats t the new nes and vice versa nce at a time. Add als cnversin functins between the new frmats. Create new blitters that can cnvert frm the ld frmats t the new ne. Page 143

144 Update the vide::cimage::blit() functin s that the new blitters are returned when apprpriate. Create new cnversin functins that take blcks f pixels and cnvert them frm every frmat t every ther ne. Update vide::cclrcnverted:: cnvert_viafrmat() s that these cnverters are returned when apprpriate. Update vide::cnulldriver::makeclrkeytexture() functins s that the new frmats are supprted. Update vide::sclr::getaverage(), vide::getred(), vide::getgreen() and vide::getblue() s that they supprt the new frmats -by using a new ptinal frmat parameter. Update vide::cnulldriver::nml16() and vide::cnulldriver::nml32() s that they call the ther functins with the apprpriate frmat parameter value. Update vide::cnulldriver::makenrmalmaptexture() functin s that it calls vide::cnulldriver::nml16() and vide::cnulldriver::nml32() with the apprpriate frmat parameter and stres the nrmal cmpnents int the right clr cmpnents Clr handling in the screensht functinality There is anther place where there is a prblem related with the clr frmat limitatins f OpenGL ES 1.x: the functin in charge f the screensht functinality. A vide driver in Irrlicht shuld be able t read the pixels frm the windw and t generate an image with them. In ur case, this is dne in a methd called COpenGLESDriver::createScreenSht(). In rder t read the pixels frm the windw, the glpixelsread() functin f OpenGL is used. In the OpenGL driver, the pixels are data in R 8 G 8 B 8 frmat inside the buffer f a R 8 G 8 B 8 image, s it wrks perfectly. In OpenGL ES, hwever, the nly allwed frmats are R 8 G 8 B 8 A 8 r the internal frmat used by the driver, which in principle is unknwn t us. The prblem arises because f the fact that there is n R 8 G 8 B 8 A frmat in Irrlicht. It wuld be pssible fr us t just create that new frmat, but this wuld result as we have seen- in frcing us t duble the number f cnversin functins, thus increasing the cde size and cmplexity. Prviding that taking a screensht is nt a very used feature, that perfrmance is nt required it is nt designed t recrd vides- and that the new frmat wuld just be needed fr this functinality, it is a better idea just t fix the prblem lcally. This can be easily dne by creating an A 8 R 8 G 8 B 8 image, reading the screen data int it in the R 8 G 8 B 8 A 8 frmat, and then interchange then cnvert it a simple pair f lps. When ding this, it shuld be taken int accunt that OpenGL will return the data in a per-byte fashin Page 144

145 (thus, in big-endian) and that the image expects t have little-endian frmat. Because f that, the cnversin will lks like the fllwing: pixel c [3] = pixel i [3] pixel c [2] = pixel i [0] pixel c [1] = pixel i [1] pixel c [0] = pixel i [2] Pseud cde 13. Cnversin frm a big-endian R 8 G 8 B 8 A 8 pixel (pixel i ) t a little-endian A 8 R 8 G 8 B 8 pixel (pixel c ). And this is the last change needed fr the OpenGL ES 1.x driver. After ding all this, we will have just finished it. 5.3 CREATION OF THE SERIES 60 DEVICE It is time fr the secnd part f the develpment. Until here, we have develped the OpenGL ES 1.x driver, which can nw be used under Windws. This means tw things: The first ne is that the engine is nw available t mdelers and develpers s that they can create cntent t be shwn with OpenGL ES fr example, cntent fr a mbile phne. The secnd ne is that we can nw almst frget abut the driver and fcus entirely in develping the device fr the S60 3 rd Editin FP1 platfrm. Once we d that, the prject will be finished. We have just said almst frget befre, as we will see, we will need t d little changes t the driver s that it uses the OpenGL ES 1.1 implementatin f the phne, when running under the new device. This part f the develpment will be mre detailed than the ne befre, because we assume n familiarity with the target platfrm. Because f this reasn, we will prvide cde smetimes. Hwever, we will maintain the general tne we have been using, and we will try nt t fcus n ur actual implementatin until the end f this sectin INTRODUCTION Develping fr a new platfrm is always difficult at first, but even mre if the new platfrm is as different t the ther nes as Symbian. Symbian itself was designed with a set f requirement, cnstraints and gals in mind that are very different t the nes f the persnal cmputer platfrms. Furthermre, the applicatin develpment prcess is als different by design (fr example, there must be a pssibility fr emulatin as the target device might nt be available fr the develper). Prviding all these, the best way t begin develping fr Symbian is t read the available bks and dcumentatin. In rder t knw abut Symbian develping in C++, [84] is the best surce available. It explains in-depth hw t use Symbian C++ and the many framewrks prvided by Symbian t develp applicatins fr mbile devices. It might als be useful t understand the internals f Symbian, depending n the cmplexity f the applicatin t be develped. In rder t d s, [40] is an invaluable resurce. There are als a great amunt f resurces n the Internet, in the frm f sample cde, technical papers and tutrials. Page 145

146 Nw that we have mentined ur surces and recmmended readings, we can prceed t explain the basics r the develpment prcess up t the detail needed t understand the fllwing pages. The first thing that shuld be stated is that the preferred language fr develping native Symbian applicatins is Symbian C++. It is called Symbian C++ because it is different frm the standard C++ defined in [85] (a list f almst all the differences can be fund at [86]). This is because Symbian C++ pre-dates the ANSI standard. Hwever, the syntax is virtually the same, and the language has evlved s as t decrease thse differences. Nwadays, with help frm sme external libraries, it is pssible t develp in Symbian C++ as if it were ANSI C++. Indeed, Irrlicht is written in ANSI C++ and we will get it t cmpile by the Symbian C++ cmpiler. Talking abut the cmpiler, anther thing that we wuld need t understand in rder t develp fr Symbian is the s-called Symbian tl chain. A great white paper abut it can be fund at [87]. In standard C++, the prcess f building an applicatin is quite simple, as it just invlves cmpiling and linking. In Symbian the prcess is a bit mre cmplicated. The fllwing illustratin taken frm that article summarizes the prcess needed fr Symbian: Illustratin 29. Symbian OS build steps. Mst f this prcess is dne autmatically by the Carbide.c++ 65, which is the IDE we will use. What we need t knw abut it is that bldmake and abld create a series f Makefiles that are later used t build fr a certain target and a certain prfile (release r debug). Cncerning the surce files bld.inf and the *.mmp files, we will explain in the next sectin hw t write the nes that ur prject will need. It is imprtant t nte that the path fllwed after calling abld is different fr the different targets. As such, it is pssible t use different cmpilers fr each f them, and indeed 65 Available fr free at : Page 146

147 it is actually the case. In rder t generate cde that runs n the emulatr (which runs n x86 machines and s executes x86 cde) a cmpiler called Nkia x86 is used. We will refer t it as WINSCW, which is the target name in which it is used. In rder t generate cde fr the actual device, there are tw main different cmpilers that can be used: GCC-E and ARM RVCT (which stands fr ARM Real View Cmpiler Tlkit). GCC-E is a free cmpiler created by CdeSurcery and based n GCC which cmes with the Symbian OS SDKs we will talk abut the SDKs in a minute-. ARM RVCT, n the ther hand, is a cmmercial cmpiler frm ARM, which is far mre pwerful but als quite expensive (which is why we will nly use GCC-E). This fact will be imprtant fr us, as the cmpiler directives are different in bth cmpilers. Carbide.c++, althugh is capable f using this tl chain, des nt cmes with it. The tl chain will be installed alng with the apprpriate libraries when we install the S60 3 rd Editin FP1 SDK 66. In ur case, apart frm that SDK we will als need OpenC/C++ 67, which will maximize the cmpatibility f Symbian C++ with ANSI C++ by the implementatin f the standard C/C++ libraries. We already talked abut these libraries in Open C/C++ (page 51). After installing all these applicatins / libraries, we are ready t begin migrating Irrlicht t the S60 3 rd Editin FP1 platfrm CREATION OF THE PROJECT As it happens when develping fr every platfrm, the first step is t create a prject in ur favrite IDE. In ur case, that will be Carbide.c++. The fllwing sectins will explain hw t d this and hw t cpe with sme errrs that might arise due t the IDE and cmpiler limitatins Cpy f the surce files due t a Make limitatin As it has been explained, Carbide.c++ uses Make in rder t cmpile and link its prjects. There is, hwever, a flaw in the way it is used, which causes the utility prgram t return the fllwing errr when used in large prjects: prcess_begin: CreatePrcess(...) make (e=87): The parameter is nt crrect. The actual errr message is lcalized, s that it is different depending n the language the machine is cnfigured t use. Fr example, in Spanish it is shwn as make (e=87): el parámetr es incrrect. The rt f the prblem is hw the multiple generated bject files are passed t the linker by Make: as cmmand-line arguments. 66 Available fr free at 913a-3c6f21eb65a5/S60-SDK mr.html. 67 Which can be dwnladed frm: _and_c++/ Page 147

148 In rder t run a prgram, Make uses the functin f the Win32 API called CreatePrcess(). As it can be seen in [88], this functin receives as parameters several strings, amng which there are tw specially relevant: an string cntaining the name f the executable file f the prgram that wants t be run, and anther with the cmmand-line parameters that have t be passed t it. This last string has a length limitatin f 32,768 characters including the terminating null character. Depending n the number and the full names (file name plus path name) f the bject files that need t be passed t the linker, the length f the string cntaining them can be greater than that limit. When that happens, the CreatePrcess() functin issues an errr that make relays as it has been seen. When this happens, there are tw pssible wrkarunds t the prblem. The first ne is trying t reduce the file names, either by changing the names f the files r the names f their paths. Anther ne is t reduce the number f generated bject files. This can be dne by cmpiling just a few surce files that include all the thers. Prviding that ur gal is t minimize the impact f the Symbian cde int the engine, it is clear that the best ptin is t have the smallest pssible path names, which can be achieved just by cpying the files in a flder called c:\w, fr example Creatin f the bld.inf file The main file f a Symbian prject is the bld.inf file, als knwn as the cmpnent definitin file. This file is used t indicate which MMP files (prject definitin files) has t be cmpiled and what fr. In ur case, this file will be quite trivial, as it will als specify that a single MMP file has t be cmpiled fr the default platfrms. This can be dne with the fllwing lines. PRJ_PLATFORMS DEFAULT PRJ_MMPFILES IrrLIB.mmp Cde 1. Pssible bld.inf file fr the Irrlicht prject. As it can be seen, the specified file is called IrrLIB.mmp, a file we will analyze right after deciding which type f library t build Different library types There are several pssibilities when it cmes t create a library in Symbian. There are tw types f libraries in Symbian: Static libraries. These libraries are linked with the executable that uses them at cmpile-time, and thus their cde is included within the applicatin executable. This lead t big executables, which in turn are able t run n their wn withut depending n external files being present. Page 148

149 Dynamic linked libraries. These libraries are nt linked at cmpile-time, and thus their cde is nt included within the executables that use them. That means that thse executables cannt run n their wn, as they need t get the libraries they use laded in memry. In Symbian there are tw types f DLLs: Static DLLs. They are autmatically laded in RAM when a prgram that uses it starts, and are unladed nce every prgram that uses them finish. Plymrphic DLLs. They have t be explicitly laded and unladed by the applicatin, and several f them can have the same set f functins. This makes them particularly useful fr plug-in systems. In ur case, the type f library that better suits ur needs is the static dynamic-linked type. Disgracefully, GCC-E is unable t built Irrlicht as a DLL f that type withut majr mdificatins due t a bug that will be explained in the next sectin. Fr this reasn, we will create a static library Prblem with writeable static data in GCC-E Accrding t [89], glbal writeable static data is any per-prcess variable which exists fr the lifetime f the prcess. In practice, this means any glbally scped data - data that is declared utside f a functin, struct, r class, and functin scped static variables. This includes variables defined in namespaces, as it is pssible t make them glbally scped by just emplying the keywrds using namespace name in a glbal scpe (see the C++ standard[85], sectin ). Symbian OS supprts writable static data in DLLs since the secnd versin f its realtime kernel (EKA2), accrding t the already mentined dcument. Hwever, the GCC-E cmpiler is unable t generate wrking cde fr DLLs in that situatin, at least the versin f GCC-E included in the S60 3 rd Editin FP1 SDK. This is a knwn issue, as can be seen in [90]. As it is said in this last dcument, the nly ptins are t use the RealView cmpiler which is nt free-, remving the writeable static data r creating a static library instead f a DLL. Remving the writeable static data can be dne by using different alternative techniques, which are explained in [89]. Unfrtunately, thse techniques are either nn-prtable they nly wrk n Symbian- r t aggressive they require many changes that will intrduce a lt f verhead n ther platfrms-. Because f these reasns, building a static library is the nly chice we have Creatin f the MMP file fr the static library The MMP file is respnsible fr setting the prperties f the prject in a platfrm and cmpiler independent way. With this data, Carbide.c++ is able t generate the apprpriate Makefiles fr cmpiling the prject fr bth the emulatr and the actual device. In the fllwing lines, we will shw the MMP used fr this prt f Irrlicht and explain why each line has been put n it. Hwever, fr a full explanatin abut MMP files, it is really cnvenient t read [91]. Page 149

150 1 /* 2 ================================================================== 3 Name : Irrlicht.mmp 4 Authr : 5 Cpyright : 6 Descriptin : The Irrlicht Engine v1.4.1 fr S60 3rd FP 1 7 ================================================================== 8 */ 9 10 TARGET Irrlicht.lib 11 TARGETTYPE LIB 12 UID 0x0 0x SYSTEMINCLUDE \epc32\include\stdapis 15 SYSTEMINCLUDE \epc32\include 16 SYSTEMINCLUDE \epc32\include\stdapis\sys 17 SYSTEMINCLUDE \epc32\include\stdapis\stlprt LIBRARY libc.lib /* Fr standard C cmpatibility */ 20 LIBRARY euser.lib /* Fr user */ 21 LIBRARY libm.lib /* Fr maths */ 22 LIBRARY libgles_cm.lib /* Fr OpenGL ES */ 23 LIBRARY cne.lib /* Fr CCeEnv */ 24 LIBRARY ws32.lib /* Fr the Windw Server */ 25 LIBRARY ptiengine.lib /* Fr the PtiEngine */ #ifdef EPOC32 28 LIBRARY libstdcpp.lib /* Fr standard C++ cmpatibility */ 29 #else 30 FIRSTLIB../udeb/libstdcpp.lib /* Fr standard C++ 31 Cmpatibility in debug */ 32 STATICLIBRARY eexe.lib 33 MACRO _WCHAR_T_DECLARED 34 #endif //This is required even if the wchar type is nt used. 37 OPTION CW -wchar_t n #ifdef ENABLE_ABIV2_MODE 40 DEBUGGABLE 41 #endif USERINCLUDE..\..\..\..\include..\..\zlib..\..\jpeglib 44..\..\libpng SOURCEPATH..\..\jpeglib 47 SOURCE jcapimin.c jcapistd.c jccefct.c jcclr.c jcdctmgr.c 48 jchuff.c jcinit.c jcmainct.c jcmarker.c jcmaster.c jcmapi.c 49 jcparam.c jcphuff.c jcprepct.c jcsample.c jctrans.c jdapimin.c 50 jdapistd.c jdatadst.c jdatasrc.c jdcefct.c jdclr.c jddctmgr.c 51 jdhuff.c jdinput.c jdmainct.c jdmarker.c jdmaster.c jdmerge.c 52 jdphuff.c jdpstct.c jdsample.c jdtrans.c jerrr.c jfdctflt.c 53 jfdctfst.c jfdctint.c jidctflt.c jidctfst.c jidctint.c jidctred.c 54 jmemmgr.c jmemnbs.c jquant1.c jquant2.c jutils.c /** Other surce files, mitted fr the sake f brevity */ MACRO IRRLICHT_EXPORTS Cde 2. MMP file fr the Irrlicht prject. Page 150

151 Lines 10 t 12. These lines specify the name f the library (which is defined as Irrlicht.lib), the target type (LIB fr a static library, DLL fr a dynamic-linked library, EXE fr an standalne applicatin, etc) and the UID f the prgram. In Symbian, every bject is identified by a set f three UIDs, which are 32 bit identifiers. Each set must be unique in the system. The meaning f the different UIDs is different depending n the ther nes. Cncretely: The UID1 identifies the structure f the file. That is, whether it is an executable, a DLL, r a file stre. The UID2 meaning depend n the UID1. Fr plymrphic DLLs, the UID2 identify the interface the DLL implements. Fr static DLL, the UID2 must be 0x D. Fr executables the UID2 is ignred. The UID3 is used t differentiate bjects with the same UID2. In fact, several bjects f the same prject can share the same UID3, such as in the case f an executable applicatin, where the executable, the registratin file, and all dcuments share must share the same UID3. In the case f a static library, such as in urs, n UID is required because it will never be installed n the perating system, as the library will be included in the applicatins using it at cmpile-time. Because f this reasn, the UIDs 2 and 3 nte that the UID1 is already specified by the target type- are set t 0x0. Mre infrmatin abut UIDs can be fund at [92] and [93]. Lines 14 t 17. These lines specify the system include directries. These are the directries where files included with the pre-prcessr #include will be searched. Files indicated between less-than and greater-than symbls (e.g. #include <e32std.h>) will nly be searched in this directries, while files indicated between qutatin marks will be searched first in the user include directries and then in these nes. The directries included fr this prject are \epc32\include\stdapis, required fr using Open C and Open C++; \epc32\include, required fr using standard Symbian functins and accessing several parts f the system; \epc32\include\stdapis\sys and \epc32\include\stdapis\stlprt, required fr using Open C++. Mre infrmatin abut these directries can be fund in the dcumentatin installed n the directries \nkia_plugin\penc\s60pencdc fr Open C- and \nkia_plugin\pencpp\s60pencppdc fr Open C++-, created during the OpenC/C++ SDK plug-in installatin. Lines 19 t 25. These lines tell which imprt libraries are required fr ur library t wrk. Nte that these are imprt libraries, which means that an applicatin using ur static library will need t include them t in rder t actually lad the required DLLs; here they are nly used fr linking. Lines 27 t 34. These lines are required t supprt Open C++ in bth the GCC-E and the WINSCW cmpiler, accrding t the Open C++ dcumentatin. The first branch is meant t be Page 151

152 executed when cmpiling fr the device, while the ther ne is meant t be executed when cmpiling fr the emulatr. In bth cases, what thse lines d is t tell the cmpiler hw t link against the Open C++ library. Line 37. This line defines a cmpilatin ptin fr the WINSCW cmpiler t include supprt fr wide characters (wchar_t), which are the Unicde cunterpart t the traditinal char type. Lines 39 t 41. These lines are generated by Carbide.c++, and make nly sense when cmpiling fr Symbian 9.4 which is nt the case, as S60 3 rd Ed. FP1 is built ver Symbian These lines indicate that the applicatin shuld be debugged by using the run-mde debug API. As this cde is cnditinal, there is n reasn t remve it; it might be useful t have it there, in the future. Lines 43 t 44. This lines indicate the user include files. It has already been said what they are. In ur case, the Irrlicht include flders are the nes added. Lines 46 t 54. These lines specify which surce files have t be cmpiled. This is dne by using tw MMP directives. The SOURCEPATH directive indicates a path, in which the files specified with the SOURCE directive are lcated. It shuld be nted that nt all the cpp files f Irrlicht have t be cmpiled. Cncretely, there sme surce files f the libraries that shuld nt be cmpiled. The best way t ensure that nly the apprpriate files are included is t get the file list frm the Makefile used fr Linux. Obviusly, any newly created surce file will need t be included here, a task that will be accmplished by the Carbide.c++ IDE itself. Line 58. This last line defines a macr, _IRR_STATIC_LIB_, which is used t indicate Irrlicht that it is being cmpiled as a static library. We will see in the next sectin where the cde dependent f this macr is Irrlicht cmpile cnfiguratin infrmatin As we have already seen, there is sme infrmatin abut the cmpilatin that needs t be passed t Irrlicht because sme f its cde depends n it. That is the case f the macr we have just mentined, fr example. This infrmatin is prcessed (by the C++ pre-prcessr) in a centralized place: the include/irrcmpilecnfig.h file. There, sme changes are needed in rder fr Irrlicht t wrk n S60. Firstly, sme macrs will need t be created s that platfrm dependent cde can be used in the rest f the engine mainly in the devices and the drivers-. This macr creatin is perfrmed in the first lines f the file. The fllwing cde can be used t generate the needed macrs: Page 152

153 // SYMBIAN #if defined( SYMBIAN32 ) # define _IRR_SYMBIAN_ # define _IRR_POSIX_API_ # if defined ( SERIES60_3x ) defined ( SERIES60_31 ) # define _IRR_S60_ # define _IRR_USE_S60_DEVICE_ # else # errr "Only S60 is supprted when cmpiling fr Symbian" # endif # undef _WIN32 // mre branches Cde 3. Cde fr generating the apprpriate macrs fr the S60 platfrm. The macr SYMBIAN32 is defined by the cmpilers (GCC-E and WINSCW) t indicate that a Symbian applicatin is being built. In that situatin, there are tw macrs that need t be defined: _IRR_SYMBIAN_. This macr will indicate further cde that Symbian OS is the target Operating System. Cde that depends n Symbian OS t wrk which des nt exists yet- will check fr this macr. _IRR_POSIX_API_. This macr indicates that POSIX rutines are available. Cde depending n this, checks fr this macr. We can ensure that because we are using Open C, which is meant t prvide supprt fr the majrity f POSIX functins frtunately, all f thse that Irrlicht uses-. The fllwing lines verify whether the target platfrm is S60 3 rd Editin, by using ther built-in macrs. If s, the fllwing macrs are defined: _IRR_S60_. This macr will indicate further cde that the targeting platfrm is S60 3 rd Editin. Cde that depends n S60 t wrk which des nt exists yet- will check fr this macr. Nte that checking fr Symbian is different than checking fr S60. As it has been mentined befre, there are several platfrm built n tp f Symbian, such as S60 r UIQ. _IRR_USE_S60_DEVICE_. This macr will indicate that the S60 device is meant t be used. There might be several devices fr the same platfrm, which is the reasn fr having separate macrs. This is nt ur case, anyway, as nly ne device will be prvided. As nly S60 3 rd Editin will be supprted, the cmpiler is taught t raise an errr if it is nt the targeted platfrm. Finally, the _WIN32 macr is undefined. This macr is used by Windws cmpilers t indicate that the Win32 API is available. Hwever, fr sme reasn, it is als defined by the WINSCW, and Irrlicht is misled by that, which shuld be avided. After defining the macrs dependent n the platfrm, the next lines f include/irrcmpilecnfig.h are devted t specifying which drivers shuld be cmpiled. In this versin f Irrlicht fr S60 neither the sftware renderers will nt be supprted they will be t slw t be useful- nr OpenGL because it is nt available- s in Page 153

154 rder t generate mre cmpact cde it is a gd idea t cmment the lines that define their macrs. These are the fllwing: _IRR_COMPILE_WITH_OPENGL IRR_COMPILE_WITH_SOFTWARE IRR_COMPILE_WITH_BURNINGSVIDEO_ Finally, it is imprt t specify tw ther imprtant platfrm-dependent parameters: the calling cnventin and the way f exprting functins. A calling cnventin defines hw a functin call has t be. This includes: Hw unique names fr functins are generated, a prcess knwn as name decratin r name mangling. Where and hw the parameters has t be passed frm the caller functin t the called ne. That is, which parameters are passed thrugh registers, which thrugh stack, and in which rder. Which registers must be saved by the caller functin t avid that the called functin verwriting it, and which has t be saved by the called functin. Where the return value r values f the called functin is stred s that the caller has access t them. Different calling cnventins can be used in different prgramming languages, perating systems and hardware architectures. In x86, fr example, there are calling cnventins such as cdecl r stdcall. In ARM which is the architecture we are targeting- there are ther different nes thse nes are nt supprted-. Fr mre infrmatin abut the x86 calling cnventins the Wikipedia has a gd summary that can be seen at [94]. With respect t ARM, the best surce f infrmatin abut this tpic is [95]. Alng the Irrlicht cde, a macr called IRRCALLCONV is used t specify which calling cnventin has t be used fr a functin. In ur case, this macr shuld be defined empty t use the standard calling cnventin. Regarding hw t exprt and functins, this refers t hw functins are made accessible frm utside dynamic linked libraries, and hw they must be declared in the applicatin using them, respectively. In ur case we will nt build a DLL fr the prblem with GCC-E already mentined, but we will take int accunt that pssibility, fr hypthetical further releases. The macrs that specify whether a DLL r a static library is being cmpiled is called _IRR_STATIC_LIB_ -the ne we defined earlier in the MMP file-, while the macrs fr specifying whether functins has t be exprted r imprted is called IRRLICHT_EXPORTS. The macr that defines the actual cde fr that peratin (exprting r imprting) is called IRRLICHT_API, and it has t have a different value depending n the value f the ther tw. The cde fr defining the afrementined macrs shuld be similar t this: Page 154

155 // Library macrs fr Symbian #elif defined(_irr_symbian_) # ifndef _IRR_STATIC_LIB_ # ifdef IRRLICHT_EXPORTS # define IRRLICHT_API EXPORT_C # else # define IRRLICHT_API IMPORT_C # endif // IRRLICHT_EXPORT # else # define IRRLICHT_API # endif // _IRR_STATIC_LIB_ # define IRRCALLCONV // mre branches Cde 4. Calling cnventins and functin exprt/imprt macrs. The cde starts with #elife and d nt end with #endif because it is meant t be put in the middle f the cde blck that defines this macrs fr the different platfrms. Once all this has been dne, the Irrlicht Symbian prject is created and the surce cde is ready t begin being mdified t run under S60 3 rd Editin CHANGES DUE TO THE COMPILER Prir t create the actual device class, sme ther changes t the current surce cde are needed, as there are parts f it dependent n the cmpiler used and the platfrm targeted. Precisely, perfrming the changes needed due t having t supprt the new cmpilers f Symbian (WINSCW and GCC-E) is a gd starting pint. The fllwing sectins will explain which mdificatins are needed s that the new cmpilers are able t generate prper machine cde fr ur recently created cde. Nte that the changes needed fr the OpenGL ES driver will be explained separately, just in the Changes t the OpenGL ES driver sectin (page 159) LibPNG calling cnventin As it was said in Irrlicht cmpile cnfiguratin infrmatin (page 152), a calling cnventin defines hw a functin call has t be perfrmed. The library embedded in Irrlicht t manage PNG files (libpng) uses the cdecl calling cnventin, which is nt available in the ARM architecture. As there are different cmpilers supprted by the library, and the way f specifying this differs in them, there is a macr in the file pngcnf.h, called PNG_API that is respnsible fr cntaining the cde that defines the cnventin depending n the cmpiler. This will allw us t specify when we have t use it and hw- and when nt. In ur case, this macr has t take tw values depending n the cmpiler used: When using WINSCW, the target platfrm is x86 and thus the _cdecl keywrd can be used s that the cmpiler generates cde cnfrming with the cdecl calling cnventin. Page 155

156 When using GCC-E, hwever, the target platfrm is ARM, and thus that calling cnventin is nt supprted. Because f that, in this case the PNG_API macr has t have n value, s that the default ARM calling cnventin is used. This suppses n prblem as the rest f the applicatin will use the same cnventin. The cde t achieve this behavir is: # ifndef PNGAPI # if (defined( GNUC ) &&!defined( GCCE )) (defined (_MSC_VER) && (_MSC_VER >= 800)) defined( WINSCW ) # define PNGAPI cdecl # elif defined( GCCE ) # define PNGAPI # else # warning "Is this the crrect calling cnventin syntax fr yur cmpiler?" # define PNGAPI _cdecl # endif # endif Cde 5. PNG_API macr definitin depending n the cmpiler. The additins dne t the riginal cde are marked in bld. In rder t differentiate which cmpiler is used, macrs are used. Please nte that the GCC-E cmpiler defines the GNUC macr, just as the GCC cmpiler des. Because f this reasn, an exceptin has t be expressly added t differentiate the tw. A warning has als been added just t help pssible develpers f new prts f Irrlicht Remval f extra cnst qualifiers There is ther issue related with the libpng library. There are sme places in its cde where the cnst qualifier is used twice in the same declaratin when the macr PNG_CONST is defined. In Micrsft Visual C++ this causes a warning being issued (cncretely a level 1 warning whse cde is C4114. Mre infrmatin abut it can be fund at [96]). In GCC-E, hwever, an errr is raised which is fine, as the C++ standard frbids that situatin-. T slve this situatin, the PNG_API macr used in thse declaratins has t be remved it has n effect, as bth with is definitin r withut it the entity declared will be cnstqualified-. Thse entities are: In the file pngerrr.c: cnst static PNG_CONST char png_digit[16]. In the file pngtrans.c: cnst static PNG_CONST png_byte nebppswaptable[256] cnst static PNG_CONST png_byte twbppswaptable[256] cnst static PNG_CONST png_byte furbppswaptable[256] Page 156

157 Byte alignment f structures In C++, by default, the memry layut f the structures is nt cmpact, because cmpilers are free t align data members in memry t reduce the number f memry access by using padding. Imagine fr example an int, whse size is typically 4 bytes. If it were lcated in the address 0x000abc1, it will span until the 0x000abc4 included. As memry is usually accessed by wrds, in rder t retrieve the entire int tw wrds (ne frm 0x000abc0 t 0x000abc3 and the ther frm 0x000abc3 t 0x000abc7) wuld be needed t be read suppsing a 32-bit architecture. This is fixed by the cmpilers by defining an apprpriate structure alignment. In a 32-bit architecture, data members are aligned in memry s that the starting address f data members is a multiple f the size f the data type. That is, chars (1 byte) can be lcated in any address, shrt ints and flats (2 bytes) can nly be lcated in even memry addresses, and ints, lng ints and dubles (4 bytes) nly in addresses multiple f 4. This way, it is never needed t read tw wrds frm memry in rder t get a data member. There is, hwever, a scenari in which this behavir is nt desirable: when trying t fill and structure in ne single memry peratin with unaligned data (fr example, read frm a file). This is the case in Irrlicht many times in its different file readers. There, headers f files are read directly int C++ structures s that they data fields can be accessed easily. In rder t d s, the structures invlved have t be byte-aligned smetimes referred as packed. The cde t tell this t the cmpiler depends n the actual cmpiler used, and s every time a structure that has t be byte-aligned is declared, cnditinal pre-cmpiler cde has t be used. In Visual C++, the cmpiler is able t maintain a stack f alignments. This stack can be used t set different scpes fr different alignments, s that structures are aligned accrding t the ne specified n tp f the stack. Once n mre structures with that alignment has t be declared, the stack is ppped. This behavir is achieved by using the #pragma pack precmpiler directive. In GCC, hwever, whenever an alignment different frm the default ne is desired fr a structure, an attribute ((packed)) directive has t be used after the structure members definitin. In WINSCW, the alignment is defined in the same way as in Visual C++, while in GCC-E it is dne just as in GCC. Prviding this, the cde t declare a byte-aligned structure, already mdified t take int accunt these tw cmpilers, is: #if defined(_msc_ver) defined( BORLANDC ) defined ( BCPLUSPLUS ) defined( WINSCW ) # pragma pack( push, packing ) # pragma pack( 1 ) # define PACK_STRUCT #elif defined( GNUC ) defined( GCCE ) # define PACK_STRUCT attribute ((packed)) Page 157

158 #else # errr cmpiler nt supprted #endif struct structurename { /* sme data elements */ } PACK_STRUCT; // Default alignment #if defined(_msc_ver) defined( BORLANDC ) defined ( BCPLUSPLUS ) defined( WINSCW ) # pragma pack( pp, packing ) #endif #undef PACK_STRUCT Cde 6. Cde t declare a byte-aligned structure. The mdificatins dne t the riginal cde fr adding WINSCW and GCC-E supprt are marked in bld. Structures that need t be byte-aligned (and thus these changes has t be dne t their declaratin) can be fund in the fllwing files: In the surce flder: C3DSMeshFileLader.h CAnimatedMeshMD2.cpp CAnimatedMeshMD3.cpp CImageLaderBMP.h CImageLaderPCX.h CImageLaderPSD.h CImageLaderTGA.h CLMTSMeshFileLader.h CMS3DMeshFileLader.cpp CMY3DStuff.h COgreMeshFileLader.h CZipReader.h In the includes flder: IAnimatedMeshMD3.h Prblem with multiple definitins f IGUIElement Smetimes in Irrlicht surce cde sme definitins are made in header files. The reasn fr this is unknwn, as it is cnsidered a bad practice (with the exceptin f template definitins, because it is harder yet pssible- t split their declaratin and definitin between files). Having the definitin and declaratin in a header file can lead t several translatin units having that definitin. Page 158

159 That is the case, fr example, with the IGUIElement class. It is defined in the IGUIElement.h header file, which is included in several ther files (such as in IGUIButtn.h, IGUIEditBx.h, etc) that lead t different translatin units. This shuld be nt a prblem, since the C++ standard [85] states in the sectin that several translatin units can have definitins fr the same class if several requirements are satisfied which is the case when thse definitins are exactly the same. GCC-E, hwever, des nt supprt this. We are nt sure whether it is due t an undcumented difference between standard C++ and Symbian C++ r it is just a flaw f the cmpiler. Nevertheless, the slutin is quite simple, as the nly change needed is t mve the definitin f the functin t a new CPP file and update the different prject files f the supprted cmpilers t include the new surce file. are: In ur case, the new CPP file is called IGUIElement.cpp, and the prject files updated Irrlicht7.1.vcprj Irrlicht8.0.vcprj Makefile In additin, the MMP file f the Symbian prject has t be updated t CHANGES TO THE OPENGL ES DRIVER Thanks t using the EGL library, the changes needed t make the OpenGL ES driver t wrk in Symbian are minimal. In the fllwing lines, we will describe them Additin f the apprpriate header files It is necessary t include the OpenGL ES header files in COpenGLESDriver.h and COpenGLESExtensinHandler.h s that the cmpiler knws the existence f the OpenGL ES functins. This shuld be dne cnditinally t being cmpiled fr S60, s a cde similar t the fllwing shuld be used after the test fr the definitin f the _IRR_COMPILE_WITH_OPENGLES_ macr, when the targeted platfrm is being checked: #elif defined(_irr_s60_) #include <GLES/gl.h> #include <GLES/egl.h> #include "glesext.h" Cde 7. Include files fr OpenGL ES under the S60 platfrm. Apart frm this nes, in the COpenGLESDriver.h file, and prir t checking the afrementined macr, the file w32std.h file has t be included if the S60 device is ging t be cmpiled. That is, a cde similar t this ne: #if defined(_irr_windows_api_) # define WIN32_LEAN_AND_MEAN # include <windws.h> // fr HWND #elif defined(_irr_use_s60_device_) Page 159

160 # include <w32std.h> // fr RWindw #endif Cde 8. Include file fr RWindw, that is needed fr the S60 device creatin functin Mdificatin f the SExprtedVideData structure If we remember frm the chapter when the OpenGL ES driver was created, there is a public data structure that is filled by the driver at creating time with its internal data, s that the user is able t access it frm the applicatin. This structure is declared in the file include/sexprtedvidedata.h. A new data element in the frm f an annymus structure has t be defined fr hlding the OpenGL ES data under the S60 platfrm. Smething similar t: #if defined(_irr_compile_with_opengl_es_) && defined(_irr_use_s60_device_) struct { //! Windw handle. /** Get with fr example with: RWindw * h = reinterpret_cast<rwindw *>(expseddata.opengleswin32.rwindw) */ vid * RWindw; //! EGL drawing surface /** Get if fr example with: EGLSurface s = reinterpret_cast<eglsurface>(expseddata.opengleswin32.eglsurface) */ vid * EglSurface; //! EGL abstract display, which might be bund t a surface /** Get if fr example with: EGLDisplay d = reinterpret_cast<egldisplay>(expseddata.opengleswin32.egldisplay) */ s32 EglDisplay; //! EGL rendering cntext, the OpenGL ES state machine /** Get if fr example with: EGLCntext c = reinterpret_cast<eglcntext>(expseddata.opengleswin32.eglcntext) */ vid * EglCntext; } OpenGLESS60; #endif Cde 9. New data member needed in the SExprtedVideDriver structure Additin f functins needed fr creating the driver Als in the sectin when the OpenGL ES driver was created, cncretely in Duplicating the OpenGL driver (page 98), the successin f functin calls needed t create the driver was explained. Sme f thse functins are device-dependent albeit being declared and defined within the driver, s they have t be recreated fr the new S60 device. This is the case f the cnstructr, the initdriver() functin and the createopenglesdriver() functin, all f them defined in the file COpenGLESDriver.cpp. The new functin definitins have t be enclsed between #ifdef _IRR_USE_S60_DEVICE and #endif. The cnstructr can be pretty much the same as the ne used fr the Windws device, but changing the HWND windw parameter fr RWindw * parameter (as the equivalent t the Windw Handlers in Windws are pinters t RWindw bjects in Symbian). Exactly the Page 160

161 same happens with the initdriver() functin, where the parameter HWND hwnd has t be replaced by a RWindw * bject again. The NativeDisplay attribute f the class has t be set t zer instead f t the device cntext. As a result f ding this, the initegl() functin will later try t use the default NativeDisplay returned by the EGL library, which is the recmmended behavir when using OpenGL ES under Symbian. In additin t this, the new OpenGLES60 data member f the ExpsedData unin shuld be used instead f the OpenGLESWin32 member, s that the internal driver data is expsed crrectly t the user. As fr the createopenglesdriver() functin, which is defined in the end f the file, it is again just the same as in Windws but fr the usage f RWindw * instead f HWND. It shuld be nted that in additin t changing the definitin f the functins, it is imprtant t als change their declaratins s that they match. The cmpiler will raise errrs in case this is nt prperly dne. After ding all this, the OpenGL ES driver is ready t run in the S60 platfrm CREATION OF THE S60 DEVICE After all the mdificatins that we have dne t the surce cde in different places, it is already cmpatible with the new platfrm. There is, thus, nly ne thing left: creating the actual S60 3 rd Editin FP1 device. Instead f referring t the cde f ur implementatin since the beginning, we will first explain hw the things that a device needs t d can be dne in the S60 3 rd Editin FP1 platfrm. This infrmatin shuld be general enugh t prvide anyne enugh knwledge t allw him/her creating his/her wn implementatin. Afterwards, nevertheless, we will explain ur particular implementatin, s as t give a cmplete idea f what we have dne and hw Creatin f a windw will be run. One f the tasks f the device is t creating the windw in which the OpenGL ES cntext T manage windws in Symbian, the API f the Windw Server is used. The Windw server is respnsible fr crdinating the access t the phne screen and input devices, as they are resurces shared between every applicatin n the phne. Amng its tasks, accrding t [97]: Clipping the drawing calls f applicatins t their windw. Send pinter events t related-applicatins nly. Send keybard events t the fcused applicatin. As we can see, the Windw Server des nt nly manage windws, but als events. We will make use f this in the future. The best way fr applicatins t access t the Windw Server is thrugh the UI Cntrl Framewrk, which is internally called CONE (an abbreviatin f Cntrl Envirnment). Page 161

162 Accrding t [98], the Cntrl Envirnment simplifies the interface t the Windw Server and prvides an envirnment fr creating cntrls. It is implemented as a single instance f the class CCeEnv, which encapsulates an active scheduler and active bjects fr cmmunicating with the windw server. This instance is created autmatically by the framewrk and a pinter stred in Thread Lcal Strage (TLS). In the case f applicatins nt using the framewrk, it has t be explicitly created, hwever. Nevertheless, in ur case, as we are writing a library, we d nt have t wrry abut hw the Cntrl Envirnment, but just that it is available thrugh CCeCntrl, CCeAppUi and thrugh its wn static functin, CCeEnv::Static(). Once the access t the Windw Server is available, there is still need fr knwing hw t create a windw with it. In rder t d s, there are certain cncepts that must be understd first. The first ne is the cncept f Windw Server Sessin. The Windw Server Sessin is the primary mean thrugh which an applicatin can cmmunicate with the windw server. In fact, by using it, it is pssible t cntrl the windws f the applicatin, t issue asynchrnus requests fr events, and even t cntrl certain system-wide behavirs. The Windw Server Sessin f an applicatin is represented by an bject f the type RWsSessin. Other imprtant cncept is the Windw Grup. Accrding t the dcumentatin, a Windw grup is the basic unit f an applicatin, in terms f the Windw Server. As such, windws have t belng t a Windw Grup t ne wned by their applicatin-. That is, the Windw Grup is the rt f the windw hierarchy tree. Windw Grups are represented by bjects f the RWindwGrup class. Prviding that, we can create a windw. All that is needed it t use the Cntrl Envirnment t btain the Windw Sessin and the Windw Grup f the applicatin, and then create a windw in the Windw Server with them. This can be dne with the fllwing cde: Page 162

163 //Get the Cntrl Envirnment CCeEnv * env = CCeEnv::Static(); if (! env ) { return; }; // Get the Windw Sessin RWsSessin WsSessin = env->wssessin; // Get the Windw Grup RWindwGrup WindwGrup = env->rtwin(); // Create the windw RWindw * Windw = new (ELeave) RWindw( iwssessin ); Windw->Cnstruct( WindwGrup, reinterpret_cast<tuint32>( this ) ); Cde 10. Creatin f a windw in Symbian using the Cntrl Envirnment. As it can be seen, the windw is created by using a tw-phase cnstructr, a typical idim in Symbian. Mre infrmatin abut this idim can be fund at [99]. It is wrth mentining the secnd parameter f the CnstructL functin. Every windw mush has a unique identifier within a Windw Sessin. The usual way f ensuring this is t cast the address f the bject that wns the windw t a TUint32 and set it as the windw identifier. This is the methd recmmended by the RWindw dcumentatin. Nw that the windw is created, there are still sme peratins that need t be perfrmed n it. The first ne is t set its extent t the desired size. This can be dne by using the methd RWindw::SetExtent(). Hwever, if the user requested a full-screen windw, we will need t btain the current windw size (which, in the case f the N95, varies depending n the screen rientatin). In rder t get this data, we need t access the s-called Sftware Screen Device. This element is part f the Windw Server, and can be used t enquire r set parameters fr the sftware screen and t determine characteristics f the physical ne 68. In rder t access it, we can use the Cntrl Envirnment again. The fllwing cde will set the extent f a windw t the whle screen area: CWsScreenDevice iwsscreendevice = env->screendevice(); TPixelsTwipsAndRtatin pixnrt; iwsscreendevice->getscreenmdesizeandrtatin( iwsscreendevice->currentscreenmde(), pixnrt ); // Set the size and psitin f the windw Windw->SetExtent( TPint( 0, 0), pixnrt.ipixelsize); 68 The sftware screen refers t the lgic representatin f the screen while the physical ne is the hardware. Page 163

164 Cde 11. Setting the extent f a windw t the entire screen. Finally, it is a gd idea t ensure that the windw is displayed, can receive events and is t the fregrund. This can be dne by using: Windw->Activate(); Windw->SetVisible( ETrue ); Windw->SetNnFading( ETrue ); Windw->SetShadwDisabled( ETrue ); Windw->EnableRedrawStre( EFalse ); Windw->EnableVisibilityChangeEvents(); Windw->SetNnTransparent(); Windw->SetBackgrundClr(); Windw->SetOrdinalPsitin( 0 ); Cde 12. Setting the extent f a windw t the entire screen. A full explanatin abut what each methd des cn be find in the dcumentatin fr RWindw in the Symbian Develper Library, available at [100] Get the current vide mde There is ne f public methds f the IrrDevice class that can be used by t get a list f the available vide mdes. As changing the vide mde f a mbile device is nt recmmended, we will nly return the current vide mde. A vide mde is a structure cntaining the screen size in pixels and a clr depth (Irrlicht was nt designed with multiple screen rientatins in mind). We already saw hw t get the current screen size when we saw hw t create a full-screen windw. It is dne by using a cde similar t: CWsScreenDevice* WsScreenDevice = CCeEnv::Static()->ScreenDevice(); TPixelsTwipsAndRtatin pixnrt; WsScreenDevice->GetScreenMdeSizeAndRtatin( WsScreenDevice->CurrentScreenMde(), pixnrt); Cde 13. Cde t get the current screen size. Once dne, the structure pixnrt will cntain the screen size n its public members ipixelsize.iwidth and ipixelsize.iheight. Cncerning the clr depth, it can be returned by calling the DisplayMde() methd f the Screen Device. This will return a cnstant representing the current clr mde. The fllwing table relates each cnstant with its clr depth. Display mde cnstant Assciated clr depth EGray2 1 EGray4 2 EGray16 4 EClr16 4 EGray256 8 EClr256 8 Page 164

165 EClr4K 12 EClr64K 16 EClr16M 24 EClr16MU 32 EClr16MA 32 Table 26. Display mdes and their respective clr depths Sleeping the applicatin The Irrlicht engine shuld be able t suspend itself fr a certain amunt f time s that ther applicatins are executed. This behavir can be enfrced by the user by calling the yield() r sleep() methds f the device. The difference between bth is that yield suspends the applicatin fr the minimum amunt f time, while the ther let the user specify the sleeping time. Suspending an applicatin in Symbian can be dne by calling the User::After() methd. This methd receives a certain amunt f time in micrsecnds, which is the time that the applicatin will be suspended. As 1 micrsecnd is nt very much time, it is recmmended t use a higher value fr the yield() methd fr example, Management f events There are sme events t which Irrlicht must be able t respnd. This includes windw events and user input events, fr instance. As we have previusly said, the Windw Server is respnsible fr sending thse events t the applicatin, and it is up t this ne t capture them and react accrdingly. In rder t handle events, an bject respnsible fr receiving the event ntificatins frm the Windw Server will be. Due t the nature f event, these are sent asynchrnusly t the applicatin. T address this issue, Symbian OS makes use f the Active Object pattern. In this pattern, there are three main rles (in Symbian): Asynchrnus Service Prviders. These elements are able t handle requests frm Active Objects and t ntify the Active Scheduler when it has been prcessed. An Active Scheduler. This element is in charge f receiving ntificatins frm the asynchrnus service prviders and t identify the Active Object that make the request and ntifying it f the result. Active Objects. These elements are the nes that make asynchrnus (i.e. nnblcking) requests t the Active Service Prviders. They will receive the result n cmpletin frm the Active Scheduler in which they are registered. The Asynchrnus Service Prviders run in separate threads, while the Active Scheduler and the Active Objects are run in the same thread as the applicatin. Mre abut this pattern in Symbian can be fund at [101] and [102]. Page 165

166 In ur case, the Asynchrnus Service Prvider is the Windw Sessin. It will be in charge f receiving a request fr an event ntificatin. This request will be answered as sn as an event is captured by the Windw Grup. When this happens, then Active Scheduler will ntify the Active Object, which will then ask the Windw Sessin which event ccurred. Implementing an Active Object is quite easy in Symbian, as it can be dne by just inheriting frm the CActive class. This class has tw virtual methds that need implementatin, which are: RunL(). This is the methd called whenever a request is cmpleted by the Asynchrnus Service Prvider. In ur case, it will be called when an event has ccurred. Here is where the Active Object will inquiry the Windw Server abut the data related with the event (which can be dne by calling the GetEvent() f the Windw Sessin bject. Afterwards, the Active Object will renew the request fr events. DCancel().This is the methd t be called whenever the request wants t be cancelled. It has t ntify the Asynchrnus service Prvider abut that. In additin, the Active Object will have t be assigned a pririty, register itself in the Active Scheduler, and t make the requests upn cnstructin. In ur case the pririty will be CActive::EPrirityUserInput, as the Active Object is ging t handle that, the user input, amng ther things. It is als imprtant t cancel the request when the Active Object is destryed. A sample cde fr all these peratins wuld be: ActiveObject::ActiveObject() : CActive( CActive::EPrirityUserInput ) { // Get the Windw Server Sessin and stre it in an attribute WsSessin = CCeEnv::Static()->WsSessin(); // Add urselves t the applicatin active scheduler CActiveScheduler::Add( this ); // Make the request fr event ntificatin WsSessin.EventReady( &istatus ); } // Set that we have an utstanding request SetActive(); Cde 14. Initializatin f the Active Object fr handling Windw Server Event ntificatins. ActiveObject::~ActiveObject() { // Cancel the request dcancel() } Cde 15. Destructr f the Active Object. Page 166

167 ActiveObject::RunL() { // Get the event that triggered the ntificatin TWsEvent wsevent; WsSessin.GetEvent( wsevent ); // See what t d with the event TInt eventtype = wsevent.type(); switch( eventtype ) { /** Prcess the events */ }; // Request fr mre events. WsSessin.EventReady( &istatus ); } // Again, set that we have an utstanding request SetActive(); Cde 16. RunL() methd f the Active Object. ActiveObject::dCancel() { // Ntify the Windw Server that we cancel the request WsSessin.EventReadyCancel(); } Cde 17. dcancel() methd f the Active Object. Nw that we knw hw t receive events, the next issue can be addressed: which events t react t and what t d with them. In Irrlicht, the fllwing events need t be handled: Key dwn and Key up events. These events are issued when the user press and release a key, respectively. We need this data t enable user interactin. They are cdified as EEventKeyDwn and EEventKeyUp. Device screen device changed. This event is issued whenever the size f the device screen changes. That is, when the screen is rtated. These data is needed t resize the windw accrdingly and t update the cameras (if the aspect rati varies) and the class respnsible fr the muse mvement (there is n muse in the device we are targeting but, as we will see, it will be emulated). It is cdified as EEventScreenDeviceChanged. Windw fcus gained and lst. These events are issued when the windw f the applicatin gains the fcus it is sent t the fregrund- r lses it it is sent t the backgrund- respectively. We need this data, as the user might ask fr it thrugh the Irrlicht API (cncretely thrugh the methd called irr::irrdevice::iswindwactive()). These events are cdified as EEventFcusGained and EEventFcusLst respectively. Hw t perfrm thse peratins is implementatin dependent. We will see what ur cncrete implementatin des in the upcming sectin Our implementatin (page 182). Page 167

168 Design f the user input management Irrlicht is designed t be used in a device with tw different input methds: a standard keybard and a pinting device (a muse, a tuchpad, a trackball, etc). The prblem is that the N95 as mst mbile phnes withut a tuch screen- lacks them. Because f that reasn, they have t be emulated. The N95 has is a typical mbile keybard the standard ITU-T keypad 69 plus sme ther sft keys 70 - and sme ther buttns such as the nes fr multimedia r the camera. In additin t that, the N95 is equipped with accelermeters, which are able t measure the tilt f the phne in three different axes. Emulating a full keybard by using the keybard f the mbile phne is smething very cmmn. In fact, it is dne by every mbile phne t allw the user t write alphanumeric characters fr example, fr SMS-. There are several ways t d this. Fr example, in Series 60 the fllwing input methds are used availability depends n phnes and languages-: Multi-tapping. It cnsists in binding several characters t the same key. The user can then press the key as many times as he wishes t cycle thrugh the different characters f the key, and whenever he stps pressing it fr a fixed amunt f time r he presses anther key, the character is cnsidered chsen and set as part f the input. Predictive. Smetimes referred as Single-tapping. Again, several characters are binding t the same key. Hwever, this time the user has t press each key nly ne. Each time a key is pressed, all the keys that has been pressed since the last punctuatin mark r space that is, since the beginning f the current wrd- are analyzed t try t guess which wrd the user is trying t intrduce. The wrds guessed has the same number f characters as the keys pressed. Wrd cmpletin. It is similar t the predictive input methd, but the length f the wrds guessed can be lnger than the number f keys pressed. Pinyin. This is a Chinese input methd where the user inputs phnetic spelling in Latin characters fr the Chinese characters that he wants t intrduce. Strke. This is anther Chinese input methd where the user can build Chinese character frm a set f strkes. Zhuyin. Anther Chinese input methd, where the user enters strings f Zhuyin symbls t prduce a Chinese character. Since there are mre Zhuyin characters than keys in a nrmal keybard, usually multi-tapping is used t enter them. Pinyin phrase. Similar t the Pinyin methd, but fr the ability t let the user intrduce cmplete phrases instead f just ne character at a time. Zhuyin phrase. Similar t the Pinyin phrase cncept but applied t Zhuyin. 69 The s-called ITU-T keypad is the typical phne keypad with 12 keys: the number keys frm 0 t 9, the asterisk and the hash. The ITU-T is a standard frm the Internatinal Telecmmunicatin Unin. 70 Sft keys are keys shwn near a display screen, and whse functin depends n the text shwn next t them at a given mment. Page 168

169 (This is nly a list f the different input methds using the ITU-T keypad, but there are mre input methds in Series 60. A mre cmprehensive list f all f them can be fund at [103]. In ur case, fr the sake f simplicity we will nly use multi-tapping fr emulating the cmplete alphabet f a full standard keybard. Hwever, ther keys different frm the letters are needed, s the extra buttns available in the device will be needed. Cncerning the pinting device, there are tw different ptins. Once ptin is t use the built-in accelermeters f the N95 t emulate it, and the ther is t use the keybard. Bth methds have their advantages and drawbacks, which can be summarized in the fllwing table: Use the accelermeters Use the keybard It requires less keybard keys nly the nes fr emulating the buttns. It is quite innvative. It is nt very intuitive it is different than in the Wii cnsle, as in the mbile mving the device implies mving the display als. It is nt efficient, as plling is required t retrieve the state f the accelermeters. It is exclusive t the N95. It requires keybard keys fr mvement as well as fr the buttns. It is mre typical. Indeed, it is the ptin used in the Nkia web brwser. It is easy t use. It is easy and efficient t implement, and can make use f event handlers. Every mbile phne has a keypad. Table 27. Prs and cns f the different methds fr emulating a pinting device. Because f all the afrementined reasns, we chse t emulate the pinting device by using the keypad. In rder t d s, the fllwing keys were chsen t be used: the arrw keys, the squared buttn, the pen key, and the delete key. The fllwing image shws that keys alng with their rle in the pinting device emulatin: Illustratin 30. Keys used fr pinting device emulatin. The prblem is that the arrw keys and the delete key are als needed t emulate the full standard keybard (if we emulated just the alphanumeric keys, n keys wuld be left fr ther purpses). In rder t be able t d s, we can make use f tw different input mdes. Page 169

170 Numeric mde with pinting device emulatin. In this mde, the pinting device will be emulated by using the keys already mentined, and the keypad can be used t enter numeric values. Multi-tapping. In this mde, the pinting device is nt emulated by using the abve keys. Instead, they are used as arrw keys and delete key actually, backspace-. The pen and the squared keys are used as themselves that is, they have their wn key cde. In rder t switch between input mdes, the hash key is used as it is nt used very ften during numeric mde, and the hash can be intrduced by pressing the 1 key several times-. As the arrw keys as such will nly be available in a different mde than the pinting device emulatin, but bth are needed t cntrl the built-in FPS camera, fr example, it is recmmended t change the default key bindings used in Irrlicht. Fr example, by assigning the numbers 8, 4, 6, and 2 t the frwards, left, backwards, and right mvement f the camera, as these can be intrduced in the numeric mde. Disgracefully, the key cdes used by each element are hard-cded in them -fr example, the keys used by the FPS camera are defined in the CFPSCameraSceneNde class, the nes used by the edit bxes are defined in the CGUIEditBx class and s n-. It is recmmended t mve them t a single header file r t several ne that are included cnditinally, depending n the target platfrm-. Fr example, a header file such as the fllwing ne culd be used t select which key bindings t use this is, indeed, the header file we have used in ur implementatin-: #ifndef I_DEFAULT_KEY_BINDINGS_H_INCLUDED #define I_DEFAULT_KEY_BINDINGS_H_INCLUDED #include "IrrCmpileCnfig.h" #ifdef _IRR_SYMBIAN_ # include "SymbianKeyBindings.h" #else # include "StandardKeyBindings.h" #endif #endif /* I_DEFAULT_KEY_BINDINGS_H_INCLUDED */ Cde 18. Header t be included by every file where key bindings are used. Where StandardKeyBindings.h is as fllws: #ifndef I_STANDARD_KEY_BINDINGS_H_INCLUDED #define I_STANDARD_KEY_BINDINGS_H_INCLUDED #include "Keycdes.h" // Camera FPS Scene Nde #define CAMERA_FPS_MOVE_FORWARD #define CAMERA_FPS_MOVE_BACKWARD irr::key_up irr::key_down Page 170

171 #define CAMERA_FPS_STRAFE_LEFT #define CAMERA_FPS_STRAFE_RIGHT #define CAMERA_FPS_JUMP_UP // GUI Edit Bx #define EDIT_BOX_SELECT_ALL #define EDIT_BOX_COPY #define EDIT_BOX_CUT #define EDIT_BOX_PASTE #define EDIT_BOX_TO_START #define EDIT_BOX_TO_END #define EDIT_BOX_RETURN #define EDIT_BOX_LEFT #define EDIT_BOX_RIGHT #define EDIT_BOX_UP #define EDIT_BOX_DOWN #define EDIT_BOX_BACK #define EDIT_BOX_DELETE // GUI Buttn #define BUTTON_PRESSED_1 #define BUTTON_PRESSED_2 #define BUTTON_CANCEL // GUI CheckBx #define CHECK_BOX_PRESSED_1 #define CHECK_BOX_PRESSED_2 #define CHECK_BOX_CANCEL // GUI CmbBx #define COMBO_BOX_PRESSED_1 #define COMBO_BOX_PRESSED_2 #define COMBO_BOX_CANCEL #define COMBO_BOX_UP #define COMBO_BOX_DOWN #define COMBO_BOX_START_1 #define COMBO_BOX_START_2 #define COMBO_BOX_END_1 #define COMBO_BOX_END_2 // GUI Scrllbar #define SCROLLBAR_UP_SMALL_1 #define SCROLLBAR_UP_SMALL_2 #define SCROLLBAR_UP_LARGE #define SCROLLBAR_DOWN_SMALL_1 #define SCROLLBAR_DOWN_SMALL_2 #define SCROLLBAR_DOWN_LARGE #define SCROLLBAR_START #define SCROLLBAR_END // GUI Listbx #define LIST_UP #define LIST_DOWN #define LIST_START #define LIST_END #define LIST_PAGE_UP #define LIST_PAGE_DOWN #define LIST_SELECT_1 #define LIST_SELECT_2 irr::key_left irr::key_right irr::key_key_j irr::key_key_a irr::key_key_c irr::key_key_x irr::key_key_v irr::key_home irr::key_end irr::key_return irr::key_left irr::key_right irr::key_up irr::key_down irr::key_back irr::key_delete irr::key_space irr::key_return irr::key_escape irr::key_space irr::key_return irr::key_escape irr::key_space irr::key_return irr::key_escape irr::key_up irr::key_down irr::key_home irr::key_prior irr::key_end irr::key_next irr::key_left irr::key_up irr::key_prior irr::key_right irr::key_down irr::key_next irr::key_home irr::key_end irr::key_up irr::key_down irr::key_home irr::key_end irr::key_prior irr::key_next irr::key_return irr::key_space // GUI Message bx Page 171

172 #define MSGBOX_OK #define MSGBOX_YES #define MSGBOX_NO #define MSGBOX_CANCEL // GUI Envirnment #define GUI_NEXT_ELEMENT irr::key_return irr::key_key_y irr::key_key_n irr::key_escape irr::key_tab #endif /* I_STANDARD_KEY_BINDINGS_H_INCLUDED */ Cde 19. Standard key bindings fr different actins in Irrlicht. It is recmmended t create this files in the include flder, s that the user f the engine has access t them fr read-nly purpses, f curse-. Apart frm creating these new files and macrs, it is f curse necessary t update the files with the hard-cde bindings t use the new macrs. Thse files are: CCameraFPSSceneNde.cpp CGUIButtn.cpp CGUICheckBx.cpp CGUICmbBx.cpp CGUIEditBx.cpp CGUIEnvirnment.cpp CGUIListBx.cpp CGUIMessageBx.cpp CGUIScrllBar.cpp All f them lcated in the surce flder. Cncerning the pssible key cdes t use, their lcated in the file include/keycdes.h, which wuld f curse need t be updated s that it includes the new keys f the S60 device. These are the sft keys, the pen key, the asterisk and the hash key. In rder t add them, the nly thing t be dne is t add sme new members f the EKEY_CODE enumeratin. Finally, we need t knw hw t pass the key events resulting frm the pinting device and keybard emulatin t the engine, s that they are received by the scene ndes, the GUI elements and s that events are generated fr the user f the applicatin. The CIrrDeviceStub class, frm which all Irrlicht devices inherits, ffers a methd called psteventfrmuser() that is able t take an element f type SEvent which represents an event- and pass it t the inner layers f the engine. This is just what we need but fr multitapping, as we will see later. Nw, the fllwing sectins will nw describe hw t emulate the pinting device in an efficient way, and hw include the multi-tapping supprt in the S60 device Pinting device emulatin As it has been said, we need t emulate a pinting device. We have already chsen even which keys t use, but there are still tw things that need t be addressed: hw the pinter Page 172

173 mvement will be simulated, and hw the pinter is t be shwn n the screen. Let begin with the first issue. A typical pinting device sends cntinuus feedback t the perating system, infrming f the changes f psitin f the pinter. In the case f the keypad, there is n mvement, but just tw pssible events: when the key is pressed, r when the key is released, and there is n cmmunicatin in between well, there might be, but it is better nt t relay n it. This leaves us tw pssible ptins fr emulating the pinter mvement: Map a key status change t a pinter psitin change. That means that the pinter wuld nly be mved whenever a key changes its state that is, when it is pressed, released, r in bth cases-. The directin in which the pinter wuld mve wuld depend n the actual key. Simulate the mvement f the pinter whenever a key is held pressed. That means that whenever a key is pressed, and until it is released, the pinter wuld mve at a certain speed. The first ptin is the easier t implement, as we wuld nly have t respnd t key events. It presents tw prblems, hwever. The first ne is that cntinuus mvement wuld nt be pssible, due t the physical time needed between tw similar key events in a single key that is, the minimum time elapsed since a key is pressed, released, and pressed again. The secnd ne is the difficulty t set a suitable granularity that is, the distance travelled by the pinter as a result f a single key event-. If the amunt f pixels mved is t much, fewer key events will be needed t mve the pinter frm a place t anther. Hwever, it will be impssible t make precise mvements. On the ther hand, if the distance is set much smaller, mvements will be precise, but the number f key events and thus key strkes- needed t mve a big distance will be higher, which is incnvenient fr the user. The secnd ptin slves these prblems partly. Cntinuus mvement wuld be available in any f the fur directins fr which there a key, and fr the fur diagnal directins that can be achieved by pressing tw keys at the same time. In additin, granularity is nt such a prblem, because the number f key strkes needed des nt depend n it nevertheless, the smaller the pinter speed, the mre time the user will have t hld a key pressed t mve it a big distance. Hwever, this is nt such a big prblem as the ther-. On the ther hand, implementing this slutin is mre difficult, because the pinter mvement has t be simulated between events. Anyway, its advantages utperfrm that prblem, s that is the ptin we have chsen. There are tw different ways f simulating the pinter mvement between key events: Having a separate thread updating the pinter psitin peridically. This ptin is the ne that resembles the mst hw a pinter behaves. It als ensures that events can be sent t the user fr every pinter mvement. Updating the pinter psitin whenever it is requested. This ptin is far less accurate, as n muse pinter mvement is generated until its psitin is Page 173

174 requested. This means that if n ne asks fr the pinter psitin, n events will be generated by the engine. It has, hwever, the great advantage that it can be implemented synchrnusly with the applicatin, s a new thread is nt needed. Furthermre and mre imprtant-, as pinter psitins are nly calculated whenever needed, n intermediate peratins are perfrmed, s there is a huge gain in efficiency. In ur case, the latter was chsen, as efficiency is really an issue in a platfrm as limited in calculating pwer as a mbile phne. The algrithm is, thus, as fllws: Whenever a key event ccurs. Update the pinter psitin. Stre which key has been pressed r released. This can be dne by using an array indexed by key cde. Whenever the pinter psitin is requested. Update the pinter psitin. Return the pinter psitin. Hw t update the pinter psitin. Fr each key If it is pressed Calculate distance = time_since_last_update * speed Mve the pinter that distance in the directin f the key Set t zer the variable string the time since the last update. Pseud cde 14. Algrithm fr keeping the pinter psitin up t date. It is wrth mentining why it is needed t update the psitin f the muse pinter whenever a key is pressed r released. Suppse the pinter is in the psitin distance mved is, thus,. After a time, its psitin, that is, it fllws the usual frmula fr a unifrm rectilinear mvement. The. The prblem is t find the directin f, which depends n the which keys has been pressed during and fr hw lng. In fact, will be the average f the velcities f the keys, weighted by the time they have been pressed: Where is the time the key has been held since the last update. In rder t calculate this, we wuld need fur variables t stre thse times. Hwever, if we update the psitin f Page 174

175 the pinter every time befre a key is pressed r released, we can assure that all the keys that are pressed by the time f the update has been pressed all the time since the last update. This way, we have that and that S: And, substituting in the distance frmula between updates (s ), we have that: Which is the frmula used in ur algrithm t calculate the distance travelled by the muse pinter since the last update. This way, we nly need ne variable fr hlding that time. Anther thing that has t be cnsidered is that it might be needed t stre the pinter psitin in a flating pint number, depending n the velcities bund t the different keys. Suppse that the pinter is being painted n the screen. Whenever the pinter has t be painted, its psitin is requested, which triggers an update f the pinter psitin. As this peratin happens nce every frame, the time elapsed between updates can be as little as a few millisecnds (fr example, if we are painting at 100 fps, which is pssible in simple GUI applicatins, there wuld be an update every 10 millisecnds). If the velcities fr the mvement keys are less than 100 pixels per secnd, then the pinter will never mve, as in every update its psitin wuld change less than a pixel, which wuld be truncated t zer. Furthermre, if the velcity were 199 pixels per secnd, the pinter wuld get nly mved 100 pixels per secnd anyway, as the 1.9 mvement between updates wuld be truncated t 1. Once we knw hw t simulate the pinter mvement, there is still tw things remaining: hw t react t screen rientatin changes, and hw t paint the pinter n the screen. In ur target device, it is pssible t rtate the screen. This has tw different effects: ne is that the hardware key binding are changed, which is f n relevance fr us in fact, it is cnvenient- and that the actual windw size is mdified (the width and height values are exchanged). In this situatin, we have several ptins: Page 175

176 Keep the pinter in the same psitin. Basically, the muse pinter remains in the same psitin, but clamped t the new height and width (s as t frbid it being utside the screen bundaries). Exchange the crdinates f the pinter psitin. This way, the muse wuld remain in the same relative psitin, but nly if the windw crdinates are als exchanged (which has nt t be necessarily the case in a nn-full-screen windw). Keep the pinter in the same relative psitin. That means updating the pinter crdinates s that: This way, if the pinter is centered r in a crner, n matter hw the windw size varies, it will keep centered r in the same crner. The best ptin is the last ne. Using the secnd ptins has n pint, since the third ne is mre general and requires little mre cmputatin which is nt an issue, since the windw size des nt change frequently-. As f the first and the third ne, the reasn fr chsing the latter is related t hw the FPS camera behaves, when it cmes t 3D graphics, and t the fact that resizing the cntent f a windw when the windw is resized (i.e. use a liquid layut) is a cmmn thing t d. The fllwing illustratin shws the difference between using the first methd in a 2D GUI and a 3D applicatin: Illustratin 31. Changes in the pinter psitin due t a windw resize. It can be seen that, by just clamping the crdinate t the new dimensins, the relative psitin f the pinter is changed. In the case f the 3D dem, this suppses an undesired camera mvement. By keeping the relative psitin f the pinter, hwever, this prblem is slved, and the result in the 2D GUI is much intuitive t. Finally, cncerning hw t paint the pinter, there are several pssible appraches that can be taken, but nt all f them are actually crrect: Use a custm scene nde. We culd use a custm scene nde, that can be added t the scene tree whenever the muse pinter has t be drawn. This apprach has Page 176

177 tw main prblems. The first ne is that every scene nde is drawn befre the GUI elements, s the pinter will always be drawn belw thse elements, which is quite a bad idea. The secnd prblem is even wrse. It results that there is n need fr calling the draw() methd f the Scene Tree if the applicatin makes use f GUI elements nly. In that case, the pinter will never be drawn, which is even wrse that having it belw the cntrls. Use a custm GUI element. We culd create a custm GUI element that represents the pinter. As GUI elements are drawn abve the scene nde elements, we culd ensure that the pinter will be drawn abve everything else. Hwever, nce again, there is n need t call the draw methd f the GUI Envirnment in applicatins that d nt make use f a GUI. In thse situatins, the muse pinter wuld be never shwn. Draw the pinter in the endscene() methd f the driver. This methd is always called whenever the scene has already been drawn. At that stage, painting the pinter wuld ensure that it is painted abve everything else. Furthermre, as calling this methd is cmpulsry, it will always be painted if required. The nly prblem f this last apprach is that in thery drivers shuld be deviceindependent. If we make the OpenGL ES driver t paint the pinter n the screen, it will d s even when used in Windws, which is nt desirable. It is, f curse, pssible t slve this by enclsing the cde t draw the pinter between #ifdef _IRR_SYMBIAN_ and #endif preprcessr instructins. Hwever, this is a bad design decisin, as whenever a new driver gets added fr Symbian, the develper will need t remember t include this cde n its wn endscene() methd t. Because f this reasn, we have decided t break the Irrlicht API t add a beginscene() and endscene() methds t the IrrDevice element. The users are meant t call this methd nw, instead f the methds f the vide driver. This way, we can include the cde t render the pinter in the beginscene() methd f ur S60 device, after the call t the vide driver wn methd, and it will wrk independently f the driver used fr renderizatin. In rder nt t break API cmpatibility, hwever, we have kept the vide driver beginscene() and endscene() methds public, s that ld cde can still call them. Hwever, in an applicatin nt ding s, the pinter will never be shwn. This slutin seems t be a gd trade-ff. Users unaware f this change are able t keep using Irrlicht just as befre, while users develping fr the new platfrm (S60) will just have t change the cde a little. In return, this slutin ffers the pssibility f prting Irrlicht t new targets in which the same prblem r very similar nes- culd arise withut having t tuch the existing vide drivers. Nw that we have where t put the cde t draw the pinter, we need t knw hw. The first step is t get an image t use as pinter, the nly restrictin is that is has t be in a frmat that can be read by Irrlicht. As having the engine depending n external files is nt a Page 177

178 gd idea, a prgram such as Bin2H 71 can be used t cnvert the file t a header file cntaining an array filled with the its binary data. This array can then be read just as a nrmal file- by Irrlicht t generate an image, which after being turned int a texture can be rendered in the screen easily by using the vide driver. The cde t d all this is: // Initialize the needed variables vide::iimage * image; i::ireadfile* file; vide::itexture* texture; // Create a virtual file frm the array f binary data file = i::creatememryreadfile( arrayofbinarydata, sizeofthearray, "name f the file", false); // d nt try t free the array // Read the image frm the virtual file image = VideDriver->createImageFrmFile(file); // Create a texture frm the image texture = VideDriver->addTexture( name f the texture", image ); // Drp the image and files, since they are nt needed anymre image->drp(); file->drp(); Cde 20. Creatin f a device-dependent texture frm an array f binary data. This nly needs t be dne nce. As we will see, in ur implementatin this is dne in the cnstructin phase f the bject representing the emulated pinter. Later, t render the texture at a certain psitin f the screen, a call t IVideDriver::draw2DImage() can be used Multi-tapping supprt The next and final- step fr cmpleting the input management is t supprt multitapping fr allwing intrducing alphanumeric characters. We shall begin by examining indepth hw multi-tapping behaves. This is best shwn n a flw diagram: 71 Actually, there are several prgrams named Bin2H, every ne f them frm a different authr. The thing is that all f them d the same, s which ne t use is actually irrelevant. The ne we have used fr ur implementatin can be fund at Page 178

179 The text cursr is at a certain empty psitin The user presses a key A digit Which key? The delete key An unrelated key The first character bund t it is shwn The last character is deleted The cursr remains belw it The cursr mves t the left (the psitin f the remved character) What happens next? N time is pressed fr a certain time Or an unrelated key is pressed Anther key is pressed The same key is pressed The delete key is pressed The character shwn is replaced by the next character bund t the key The text cursr mves t the right The last character is deleted The text cursr mves t the right The cursr remains at the same psitin Illustratin 32. Flwchart f the multi-tapping algrithm. In rder t add multi-tapping supprt t Irrlicht, we have t knw hw t perfrm all this peratins. There is a class, part f the Series 60 API, called PtiEngine. The main purpse f this class is t assists develper t implement the different input mdes. The first thing that needs t be dne is the creatin f a PtiEngine bject, and t set which input mde we desire and fr which language. This can be dne with a cde similar t the fllwing: Page 179

180 PtiEngine = CPtiEngine::NewL(); User::LeaveIfErrr( PtiEngine->ActivateLanguageL(User::Language(),EPtiEngineMultitapping) ); Cde 21. Creatin f a PtiEngine bject. This cde sets the input language t Multi-tapping, and the language t the language currently set in the phne settings. The way f using the PtiEngine is a bit different frm what we actually need. The PtiEngine is designed s that every input f a relevant key that is, the digits and the delete key- has t be ntified t the PtiEngine. Internally, the PtiEngine stres the input characters that has been input and updates them depending n the key events it receives. Whenever the input wants t be retrieved, the CurrentWrd() methd can be called (mre infrmatin abut this prcess can be fund at [103]. In rder t be able t use PtiEngine, we will still need t prvide it with the keys pressed. Fr ding s, we will have t use different methds depending n which key is pressed. Cncretely: If a digit key is pressed: The AppendKeyPress() methd. If the delete key is pressed: The DeleteKeyPress() methd. If anther key is pressed, we have t ntify that we want t trigger a time ut, s as t fix the last intrduced character. This can be dne by calling the CancelTimerActivity() methd. As lng as we keep the PtiEngine bject up t date, it will allw us t get the current character bund t the last pressed key, and t act in the event f a time ut. In rder t be able t d the latter, hwever, we will need t set an Observer bject, which will be ntified n the event f a time ut. T set an bserver fr the PtiEngine, a class inheriting frm MPtiObserver will be needed. This class has t prvide three methds: KeyTimerExpired(). This methd will be called whenever a time ut event ccurs. Any cde t respnd t this event shuld be lcated in this methd. LastWrdInSelectinList(). This methd will be called whenever the last item in the predictin candidate list is reached. As we are nt wrking with a predictive input mde, it will never be called fr us, s we can define it empty. FirstWrdInSelectinList(). Just as the methd abve but this time it is called when the first item is reached. Again, it is nt applicable t us, s it can be defined empty. Once the class is defined, a call t the setobserver() methd f the PtiEngine bject can be made t register an bject f that type as the current bserver fr the PtiEngine. Cncerning which actins we will need t d, what fllws is a list f all f them and hw they shuld be perfrmed: Page 180

181 Getting the last input character. We can get the last character that has been input by getting the last character f the wrd returned by the CurrentWrd() methd. This methd returns a descriptr the Symbian equivalence t the standard C++ strings- s its length can be retrieved by using its length() methd, and a single character by using the peratr[]. Nte that this is the last input character, n matter whether it is still nt fixed that is, the text cursr is still belw it- r nt. Delete a character. Apart frm sending the key event t the PtiEngine bject, we will need t remve the character shwn in the GUI. There are tw different situatins, as can be seen in the multi-tapping diagram shwn befre: the cursr might be past the character we have t remve, r just belw it. It is up t us t keep track f the cursr and the current character t differentiate bth situatins. If the cursr is belw the character t be remved, we will need t mve it t the right by sending right key press and right key release events-. Then, in rder t remve the character we have t send backspace press and release events. Replacing the last shwn character. This can be dne by just deleting that character and shwing it by sending the crrespnding key press and release events-. Mve the cursr. As it has been already said, the cursr can be mved by using right and left key press and release events. Once all this is knwn, implementing the flw diagram f the multi-tapping input methd shuld be fairly easy. There still, hwever, sme questins left. The first ne is related with hw t send the key events t the GUI. In a previus sectin we talked abut the psteventfrmuser() methd f the IrrDeviceStub class. The prblem with this methd is that it sends the event nt nly t the GUI, but als t the Scene Ndes and, eventually, t a custm event receiver set by the user f the applicatin. This is nt desired, as sme f the key events we need t send t the GUI are just faked events t shw a certain character when the user is still chsen the ne he wants t input r t mve the text cursr temprary just fr deleting the crrect character. These events shuld never get t anywhere but the GUI; we just want t send the Scene Tree and the user thse characters that are already fixed that is, the cursr has pass them-. T ensure this, we will need a new methd fr sending events just t the GUI, and ther t send events t all the ther elements but the GUI. The cde fr these methds shuld be similar t: vid CIrrDeviceS60::pstEventTGUIOnly(cnst SEvent& event) { if (GUIEnvirnment) GUIEnvirnment->pstEventFrmUser(event); } Cde 22. Cde f the methd that sends events t the GUI nly. Page 181

182 vid CIrrDeviceS60::pstEventTAllButGUI(cnst SEvent& event) { bl absrbed; if (UserReceiver) absrbed = UserReceiver->OnEvent(event); scene::iscenemanager* inputreceiver = InputReceivingSceneManager; if (!inputreceiver) inputreceiver = SceneManager; } if (!absrbed && inputreceiver) absrbed = inputreceiver->psteventfrmuser(event); Cde 23. Cde f the methd that sends events t all cmpnents f the engine, but the GUI. The secnd questin t answer what t d with the capital letters. One way t deal with them is t use separate input mdes; ne fr lwercase letters and ther fr uppercase letters. This slutin is easy t implement, and it is, indeed, the slutin we chse fr ur implementatin. Furthermre, we use three different mdes listed in rder-: Uppercase. The letters generated are always uppercases. First uppercase. The first letter generated is uppercase. Once the first key has been input, the mde switches autmatically t lwercase. Lwercase. The letters generated are always lwercases. The first uppercase input methd is ften used by the mbile phnes in their SMS applicatins, as it is very useful. Part f this usefulness cmes frm the fact that the applicatin switches t this methd autmatically whenever a dt is pressed and thus a new sentence is assumed- althugh the user reject this change a certain amunt f times which causes the applicatin t acknwledge that the user des nt want that behavir-. This, althugh relatively easy t implement, is mre than what we need fr this first implementatin f Irrlicht n the S60 platfrm, s we have chsen nt t d it. Anyway, it is wrth cmmenting that in rder t set the case t be used, the setcase() methd f the PtiEngine shuld be called. The last questin t be addressed is hw t shw the user the current input mde. Ding s is, hwever, very easy, since it can be dne just as the pinter is shwn, by just shwing an image depending n the current state in a fixed psitin. Fr the cncrete way f ding this, please refer t the previus sectin OUR IMPLEMENTATION Until nw, we have seen hw the different tasks that the device has t accmplished can be made. Hwever, we have nt entered int details abut hw t design and develp a cncrete implementatin f the device. The reasn fr ding s is that we did nt want t mix the essence f prgramming fr the Symbian architecture with ur wn implementatin details, as they are bth very different things. Hwever, it is time t explain it. What fllws is a simple UML diagram shwing the mst imprtant classes f the S60 device implementatin. Page 182

183 CActive IrrlichtDevice MPtiObserver CIrrDeviceStub «uses» ICursrCntrl CIrrDeviceS60 «uses» CS60CursrCntrl «uses» «uses» CS60FakeMuse «uses» «uses» CWsEventReceiver «uses» CS60InputHandler «uses» CS60InputHandlerPtiObserver Illustratin 33. Simplified UML diagram f ur implementatin. The uses relatinships has been included s that it is easier t identify the rle f each class at first sight. Nevertheless, we are ging t explain all them in the fllwing pages CActive This is the base class fr all Active Objects in Symbian. We talked abut this in the Management f events sectin (page 165) CWsEventReceiver This class is the active bject respnsible fr managing several windw system events. When an event is ntified t it, it decides hw t manage it. Cncretely, it prcesses the events as fllws: Key dwn and key up events: It is ntified t the Input Handler (an instance f CS60InputHandler) via its HandleEvent() methd. Screen Device changed event: It ntifies the S60 device (instance f the CIrrDeviceS60) via its OnScreenResized() methd. Fcus lst r gain events: It ntifies the S60 device via its SetWindwActiveStatus() methd. The attributes f this class are: Page 183

184 WsSessin: Windw Server Sessin. Needed as it will be the ne asked fr the cncrete events. Device: Pinter t the S60 Device. Needed t be able t cmmunicate events t it. InputHandler: Pinter t the Input Handler. Needed t be able t cmmunicate events t it. The methds f this class are: Public: Static: NewL(): Perfrms the duble-phase cnstructin f a CS60InputMethd bject. This is a cmmn methd in Symbian, classes. Mre infrmatin abut it can be fund at [104]. RunL(): Receives events frm the Windw Server. DCancel(): Called t cancel the request t the Windw Server. Private: CS60InputHandler CS60WsEventReceiver(): The first phase cnstructr. CnstructL(): The secnd phase cnstructr. This class is respnsible fr managing the user input. It maintains the state f the current input methd, implements multi-tapping, redirect events t the simulated pinting device which is actually the CS60FakeMuse class- when needed, and is able t cmmand the vide driver hw t draw the current input methd icn n the screen (s that the user is infrmed). Mst f these functinalities have been already explained in the Design f the user input management (page 168) and Multi-tapping supprt (page 178) sectins. Basically, if the input mde is the standard ne, key events related t the keys used t emulate the muse are passed t the FakeMuse bject, and the ther keys generate simple user events. On the ther hand, when in the multi-tapping mde, the cmplete multi-tapping algrithm is used in this class well, almst the cmplete algrithm. A little part is left t the CS60InputHandlerPtiObserver class. It is ntewrthy that sme enumeratins were defined in rder t be used within this class. These are: CS60InputMde IMODE_STANDARD: The input mde where there is n multi-tapping and the pinting device is emulated. IMODE_MULTITAPPING: The input mde in which multi-tapping is used. CS60CaseMde CMODE_FIRST_UPPERCASE: Indicates that the next intrduced character shuld be uppercase, but then the mde has t be switches t lwercase. Page 184

185 CMODE_LOWERCASE: lwercase letters. CMODE_UPPERCASE: uppercase letters. The attributes f this class are: Device: Pinter t the S60 Device. Needed t be able t send event t the GUI, the user, and t be able t clse it in ur implementatin, pressing the Call key clses the applicatin. This is needed because using the task switcher des nt wrk due t a bug external t ur implementatin-. FakeMuse: Pinter t the Fake Muse. Needed t emulate the pinting device we call it muse as it is the ne Irrlicht is meant t wrk with. VideDriver: Pinter t the current Vide Driver. Needed t be able t draw the status icns n the screen. PtiEngine: Helper class prvided by the S60 platfrm t aid in the multi-tapping implementatin. LastWrdLength: Attribute t keep track f the length f the wrd in the PtiEngine. PendingChar: Attribute that tells whether is a char pending t be fixed. MultitappingFirstUppercase: Texture f the Multi-tapping First Uppercase input mde icn. MultitappingUppercase: Texture f the Multi-tapping Uppercase input mde icn. MultitappingLwercase: Texture f the Multi-tapping Lwercase input mde icn. Input Mde: Current input mde. Case Mde: Current case mde. The methds f this class are: Public: Static: NewL(): Perfrms the duble-phase cnstructin f a CS60InputMethd bject. RenderInputMethdIcn(): Renders the current input methd icn. HandleEvent(): Handles an event. This is the methd used by the Private: CS60WsEventHandler t ntify events t this class. CS60InputHandler(): The first phase cnstructr. CnstructL(): The secnd phase cnstructr. FillEvent(): Helper functin that generates an event frm sme input infrmatin. changemde(): Methd that changes the current input mde. changecase(): Methd that changes the current case mde. Page 185

186 getptikey(): Methd that returns a cnstant that can be used with the PtiEngine frm the scan cde f a key CS60InputHandlerPtiObserver It was explained in the Multi-tapping supprt sectin (page 178) that certain peratins has t be dne when there is a time ut in the PtiEngine timer. In rder be ntified abut that event, an bserver was needed. This class is that bserver. Its attributes are: InputHandler: The input handler. Needed t be able t cmmunicate with it. Its methds are: Public: CS60InputHandlerPtiObserver(): Simple cnstructr. There is n need fr a tw-phase cnstructr as n cmplex peratins need t be dne in the cnstructr. Actually, that pattern is nly needed when the cnstructr can leave, which is the equivalent t thrwing exceptins in Symbian. KeyTimerExpired(): This methd is called upn a time ut event. LastWrdInSelectinList(): This methd is empty. It has t be present, as it is required by the MPtiObserver interface. FirstWrdInSelectinList(): This methd is empty. It has t be present, as it is required by the MPtiObserver interface. It shuld be nted that the CS60InputHandler class is declared as friend f the CS60InputHandlertiObserver. Friend classes are usually discuraged frm a design pint f view. Hwever, it is exactly in this situatin, where tw classes are s cupled, where it is acceptable and even recmmended, as it imprves readability and reduced verhead, t use it MPtiObserver This is the base class fr any class that wants t be an bserver f a PtiEngine bject. We talked abut this in the Multi-tapping supprt sectin (page 178) CS60FakeMuse This class is respnsible fr emulating a pinting device. Its name cmes frm the fact that the pinting device Irrlicht is meant t wrk with is a typical muse. We already explained hw this emulatin can be achieved in Pinting device emulatin (page 172), s here we will nly explain ur implementatin. Sme enumeratins were defined in rder t be used within this class. These are: Page 186

187 CS60FakeMuseButtn: S60FM_BUTTON_LEFT: Represents the left muse buttn. S60FM_BUTTON_MIDDLE: Represents the middle muse buttn. S60FM_BUTTON_RIGHT: Represents the right muse buttn. CS60FakeMuseMvement: S60FM_MOVEMENT_UP: Represents an up mvement. S60FM_MOVEMENT_DOWN: Represents a dwn mvement. S60FM_MOVEMENT_RIGHT: Represents a right mvement. S60FM_MOVEMENT_LEFT: Represents a left mvement. The attributes f this class are: Visibility: Stres whether the pinter is visible r nt. Psitin: The current psitin f the pinter. Flating-pint crdinates are used as frequent updates require sub-pixel accuracy it was already explained in the apprpriate sectin. WindwSize: The size f the current Windw. It is needed s that it can be cntrlled that the pinter crdinates never g utside its bunds. PixelsPerMillli: Hw many pixels t displace the muse pinter in the axes per millisecnd f key pressed. TimeSinceLastUpdate: Hw many millisecnds has elapsed since the last update. Needed t calculate the actual pinter displacement. Mvement: Array f the mvements currently activated because the keys triggering them are pressed-. MusePinter: Texture cntaining the muse pinter image. VideDriver: Pinter t the current Vide Driver. Needed t be able t render the muse pinter. The methds f this class are: Public: CS60FakeMuse(): Simple cnstructr f the class. ~CS60FakeMuse(): Destructr f the class. NtifyButtn(): Methd that shuld be used t ntify the fake muse that a simulated muse buttn has been pressed. It generates a simple event that is sent t the GUI, scene manager and user. NtifyMvement(): Methd that shuld be used t ntify the fake muse has been mved by pressing the crrespnding key. As it was explained, this triggers an update f the pinter psitin, and then the Mvement array is als update t reflect the change f directin. SetVisible(): Sets the visibility f the pinter. IsVisible(): Returns whether the pinter is visible r nt. SetPsitin(): Sets a psitin fr the pinter. Setting a psitin sets the TiemSinceLastUpdate variable just as a regular update. Page 187

188 Private: ICursrCntrl GetPsitin(): Retrieves the psitin f the pinter. Prir t d that, hwever, that psitin is prperly updated. SetWindwSize(): Sets the current Windw Size. This is needed, as already said, t ensure that the pinter never ges ut f bunds. RenderMusePinter(): Renders the muse pinter if it is visible. UpdatePsitin(): Updates the psitin f the muse accrding t the PixelsPerMillis speed, the values in the Mvement array and the time elapsed since the last update which can be knwn thanks t the TimeSinceLastUpdate variable. After updating the psitin, this last variable is set with the current time. This class is part f the public API prvided by the Irrlicht Engine. It is meant t allw the user f the engine t be able t cntrl the muse pinter r a similar pinting device. This class is a pure virtual class (the C++ equivalent t interfaces), which has t be specialized by every device implementatin. The methds f this class are exactly the nes that will be explained in the next class, but fr the setwindwsize() methd, that is nt in the public interface. Nevertheless, it shuld be there, actually, as the windw size can change at runtime and thus setting it fr the ICursrCntrl in the cnstructr, as it is currently dne, is nt enugh CS60CursrCntrl This class is the implementatin f the ICursrCntrl interface prvided by ur S60 device. Instead f cntrlling an actual muse, it cntrls ur fake muse. In fact, it wuld have been pssible t actually implement the pinting device emulatin in this class instead f ding it in anther class. Hwever, it is mre scalable t have tw independent classes, as that way it wuld be pssible in the future t have CS60CursrCntrl t cntrl an actual pinting device fr example a tuch screen-. The attributes f this class are: FakeMuse: The fake muse. Rect: The reference rectangle in which the pinter is allwed t mve. WindwSize: The windw size. Needed fr calculating relative psitins, fr example, as we will see. The methds f this class are: Public: CS60CursrCntrl(): Simple cnstructr. setvisible(): Used t specify whether the pinter has t be visible r nt. It just calls the equivalent methd f the fake muse. Page 188

189 isvisible(): Returns whether the pinter is visible r nt. Once again, it just calls the equivalent methd f the fake muse. setpsitin(cnst cre::psitin<f32>): Sets the psitin f the pinter t the ne specified. The crdinates are expressed as a flatingpint number between 0 and 1, being (0, 0) the tp left crner f the reference rectangle and the (1, 1) the bttm right crner. Any value utside that range is clamped. After ding the required transfrmatins, it calls the setpsitin() methd f the fake muse. setpsitin(f32, f32): It is equivalent t the methd abve. setpsitin(cnst cre::psitin2d<s32>): It sets the psitin f the pinter t the ne specified. The crdinates are expressed n pixels, being (0,0) the tp left crner f the reference rectangle and (width-1, height- 1) the bttm right crner, when height and weight are the height and weight f the rectangle. Any value utside that range is clamped. After ding the required transfrmatins, it calls the setpsitin() methd f the fake muse. setpsitin(s32, s32): It is equivalent t the methd abve. getpsitin(): Returns the psitin f the pinter inside the reference rectangle in pixels. getrelativepsitin(): Returns the relative psitin f the pinter inside the reference rectangle (that is, between the (0,0) and (1,1) range). setreferencerectangle(): Allw the user t set a custm reference rectangle. setwindwsize(): Allw the device t cmmunicate that the windw has a new size. This updates the reference rectangle and als ntifies the fake muse IrrlichtDevice This is the interface prvided by the public API f the Engine fr a device. As such, every device has t inherit frm it directly r indirectly and implement it. This class is pure virtual. The methds f this class are: Public ~IrrlichtDevice(): Destructr. beginscene(): Applicatins must call this methd befre perfrming any rendering. This methd can clear the back and z buffers. This methd was nt present in the riginal Irrlicht API, but, as we explained befre, we have added it. clsedevice(): Ntifies the device that it shuld clse itself. endscene(): Presents the rendered image t the screen. Applicatins must call this methd after perfrming any rendering. getcursrcntrl(): It prvides access t the cursr cntrl. geteventreceiver(): It prvides access t the current event receiver. Page 189

190 getfilesystem(): Prvides access t the virtual file system. getguienvirnment(): It prvides access t the 2d user interface envirnment. getlgger(): Prvides access t the message lgger. getosoperatr():it prvides access t the peratin system peratr bject. The OS peratr prvides methds fr getting system specific infrmatin and ding system specific peratins, such as exchanging data with the clipbard r reading the peratin system versin. getscenemanager(): It prvides access t the scene manager. gettimer(): Prvides access t the engine's timer. The system time can be retrieved by it as well as the virtual time, which als can be manipulated. getversin(): Get the versin f the engine. The returned string will lk like this: "1.2.3" r this: "1.2". getvidedriver(): Prvides access t the vide driver fr drawing 3d and 2d gemetry. getvidemdelist(): Gets a list with all vide mdes available. This can be cnfused, since it might seems that it is required t create an Irrlicht Device with a vide mde befre being able t get the vide mde list. This is nt the case, and indeed this is ne f the reasns why the null drive exists. iswindwactive(): Returns if the windw is active. psteventfrmuser(): It sends a user created event t the engine. It is usually nt necessary t use this. Hwever, it is needed fr supprting external input libraries -fr example fr ding jystick input-. Internally, this methd nly delegates the events further t the scene manager and the GUI envirnment, as we have seen. run(): Runs the device. Als increments the virtual timer by calling ITimer::tick(). Yu can prevent this by calling ITimer::stp() befre and ITimer::start() after calling IrrlichtDevice::run(). Returns false if device wants t be deleted. Nte if yu are running Irrlicht inside an external, custm created windw: Calling Device->run() will cause Irrlicht t dispatch windws messages internally. If yu are running Irrlicht in yur wn custm windw, yu can als simply use yur wn message lp using whatever API the perating system prvides and nt using this methd. Hwever, nte that Irrlicht will nt be able t fetch user input then. seteventreceiver(): It sets a new event receiver t receive events. setinputreceivingscenemanager(): It sets the input receiving scene manager. If set t null, the main scene manager (returned by GetSceneManager()) will receive the input. setresizeable(): It sets if the windw shuld be resizable in windwed mde. The default is false. This methd nly wrks in windwed mde. setwindwcaptin(): It sets the captin f the windw. Page 190

191 sleep(): Pause executin and let ther prcesses t run fr a specified amunt f time. It may nt wait the full given time, as sleep may be interrupted. yield(): It causes the device t temprarily stp executin and let ther prcesses run. This shuld bring dwn prcessr usage withut majr perfrmance lss fr Irrlicht CIrrDeviceStub Sme f these methds are quite trivial they are just getters r setters- and sme thers are just independent f the device implementatin. Because f that reasn, and t avid cde repetitin, there is a class that implements thse methds that can be used and indeed, it is- by the actual devices as base class t reuse its cde: The CIrrDeviceStub class. This class has the fllwing attributes: CursrCntrl: Owned pinter t the current cursr cntrl. FileSystem: Owned pinter t the virtual file system. GUIEnvirnment: Owned pinter t the 2d graphical user interface. InputReceivingSceneManager: Pinter t an input receiving scene manager. Lgger: Owned pinter t the message lgger. Operatr: Owned pinter t the OS Operatr. SceneManager: Owned pinter f the scene manager. Timer: Owned pinter t the virtual timer. UserReceiver: Pinter t a custm user receiver. VideDriver: Owned pinter t the current vide driver. VideMdeList: Owned pinter t the current vide mde list. Thse pinters referred as wned means that this class is the nly respnsible fr deleting them, and that the bjects they pint t shuld nt be deleted elsewhere that ges fr the classes mentined befre. The methds prvided by this class are: Public: CIrrDeviceStub(): Cnstructr. It perfrms certain useful actins such as creating the virtual file system r checking the library versin. ~CIrrDeviceStub(): Destructr. It releases the wned pinters. beginscene(): Only the default behavir is implemented, that is, calling the equivalent methd f the current vide driver. endscene(): As in the case f the previus methd, the default implementatin which is calling the equivalent methd f the current vide driver- is implemented here. getcursrcntrl(): Returns the cursr cntrl. geteventreceiver(): Returns the event receiver. Page 191

192 getfilesystem(): Returns the virtual file system. getguienvirnment(): Returns the 2d graphical user interface. getlgger(): Returns the message lgger. getosoperatr(): Returns the OS Operatr. getscenemanager(): Returns the scene manager. gettimer(): Returns the virtual timer. getversin(): Returns the current versin f the engine. getvidedriver(): Returns the current vide driver. getvidemdelist(): Returns the current vide mde list. psteventfrmuser(): Sends an event t the parts f the engine that shuld handle them (GUI, Scene Manager, and the user event receiver). seteventreceiver(): Allws fr setting a custm user event receiver. setinputreceivingscenemanager(): Allws fr setting a custm input receiving scene manager. Prtected: CIrrDeviceS60 checkversin(): Checks that the versin f the engine fr which the header files crrespnd is the same as the ne f the library actually being linked against. This methd is called in the cnstructr. createguiandscene(): Creates the Scene Manager and the 2d graphical user interface and ppulates the apprpriate attributes. This methd is meant t be called nce the vide driver, the peratr, the file system and the cursr cntrl has already been created. Finally, this is the actual device implementatin fr the Series 60 platfrm. It implements the methds that are nt already implemented in the CIrrDeviceStub and verrides sme f thse. The attributes f this class are: Clse: Whether the device has been asked t be clsed. DriverType: Type f the current vide driver. FakeMuse: Owned pinter t the fake muse. InputHandler: Owned pinter t the input handler. IsWindwActive: Whether the windw is active r nt. OwnWindw: Whether the windw is external r wned by the device. ScreenSize: Current screen size. Windw: Handler t the windw. WindwSize: Current windw size. WsEventReceiver: Owned pinter t the Windw Server Event Receiver. The methds f this class are (the methds that are nt part f the public API defined by the engine are written in purple): Page 192

193 Public: CIrrDeviceS60: Cnstructr f the class. It creates the OS Operatr, the windw if n external windw has been specified, the windw server event receiver, fake muse and input handler, the cursr cntrl, the vide driver and the GUI and Scene Manager. ~CIrrDeviceS60: Destructr f the class. It releases any wned pinter. beginscene(): This methd just calls the implementatin f the parent class. clsedevice(): Sets the Clse attribute t true, s that the device is clsed as sn as pssible. endscene(): This methd renders the muse pinter, the input methd icn and then calls the implementatin f the parent class. getvidemdelist(): Ppulates the vide mde list and returns it. Only the current vide mde is returned in ur implementatin. We cmmented hw t get this infrmatin in the Get the current vide mde sectin (page 164). iswindwactive(): Returns if the windw is active r nt, by returning the value f the apprpriate attribute. OnResized(): Handles that the windw has been resized. It updates the crrespnding attribute, ntifies the cursr cntrl and the vide driver, and updates the aspect rati f all the cameras in the current scene manager. This last part is nt dne in the rest f the devices, which can be cnsidered a bug. This methd is nt part f the public API f the device. OnScreenResized(): This methd gets the new screen size, updates the crrespnding attribute, changes the size f the windw accrdingly in ur implementatin, the windw dimensins are updated s that the relative size and psitin f the windw with respect t the screen are maintained- and then calls the OnResized() methd. his methd is nt part f the public API f the device. psteventtallbutgui(): Sends an event t all the engine parts that accept it but the GUI. This methd is nt inherited frm the public API. It is required by the Input handler, as we saw in the Multi-tapping supprt sectin (page 178). psteventtguionly(): Sends an event t the GUI nly. This methd is nt inherited frm the public API, just as in the case f the methd abve. run(): Increments the virtual timer by calling s::timer::tick()- and returns the negatin f the Clse attribute. setresizeable(): In ur case, this methd des nthing, as there is n way fr the user t be able t resize the windw. setwindwactivestatus(): This methd is used t ntify changes in the windw fcus. It is nt part f the public API, and it is nly used by the Windw Server Event Receiver, as explained befre. Page 193

194 Private: setwindwcaptin(): This methd, in ur case, des nthing, as there is n captin in the Symbian windws we use. We culd have emulated it, but it seemed nt necessary, as the user is still able t put whatever text he wants n the screen via the GUI. sleep(): This methd blcks the thread f the engine fr a certain amunt f millisecnds. It was explained hw t d it in the Sleeping the applicatin sectin (page 165) OTHER MINOR CHANGES yield(): This methd blcks the thread f the engine fr a minimum amunt f time s as t let ther prcesses t run. It was explained hw t d it just in the same sectin as the previus methd. createdriver(): Creates the vide driver. Depending n the requested vide driver type, it calls the crrespnding createxxxdriver() methd. We already mentined the prcess f creating a vide driver in the Changes t the OpenGL ES driver sectin (page 159). createwindw(): Creates a windw fr the engine. We have already seen hw t d this in the Creatin f a windw sectin, page 161). getscreensize(): Returns the current screen size. We have seen hw t retrieve this in the same sectin as the previus methd. Finally, prir t claim that the migratin f this Irrlicht engine was finished, tw mre changes were dne. They are nt really needed fr the engine t wrk, and s we have left their explanatin t the end New ptins added t the FPS camera Thanks t the input scheme chsen fr the S60 prt f the engine, it is pssible t use prgrams such as Nkmte (a prgram by Samir Oueldi) t emulate the muse mvement with the Nkia built-in acceleratrs. This way, tilting the mbile phne t the right will simulate a right muse mvement, and the same ges fr the left, up and bttm directins. There are sme peple, hwever, that wuld prefer a different behavir, such as having emulating an up muse mvement by tilting the phne t the bttm. This is nt pssible with the afrementined applicatin, but what we can d is t inverse the behavir f the different muse mvements, thus achieving a similar result. In rder t prvide this pssibility, the FPS camera has been updated. These changes affect the Irrlicht API, but since it is fully backwards surce- cmpatible, it suppses n prblem. The signatures f the fllwing functins have been changed: ISceneManager::addCameraSceneNdeFPS(), declared in the file include/iscenemanager. CSceneManager::addCameraSceneNdeFPS(), declared in the file CSceneManager and defined in the crrespnding cpp file. Page 194

195 CCameraFPSSceneNde::CCameraFPSSceneNde(), declared in the file surce/ CCameraFPSSceneNde.h and defined in the crrespnding cpp file. In all cases, tw bl parameters called inversehrizntal and inversevertical, with a false value by default were added. These parameters are meant t be used in the functin CCameraFPSSceneNde::animate(), where the psitin f the camera is calculated depending n the received key pressed and muse mvements since the last frame. Cncretely, the fllwing lines have t be mdified (the changes are written in bld): RelativeRtatin.Y += (0.5f - cursrps.x) * RtateSpeed * (InverseHrizntal? -1 : 1); RelativeRtatin.X = cre::clamp ( RelativeRtatin.X + (0.5f - cursrps.y) * RtateSpeed * (InverseVertical? -1 : 1), -MAX_VERTICAL_ANGLE, +MAX_VERTICAL_ANGLE ); Cde 24. Mdificatins dne t the FPS Camera s that it is pssible t inverse the X and Y axes Perfrmance issues in the trignmetric functins The first time the SpecialFX dem was run n the actual device, it exhibited a very strange behavir. Althugh it wrked fine during the first minutes, after a fixed amunt f time it suddenly reduced its frame rate t the tenth. Tracking what caused this, it was discvered that it was related with the sinf() and csf() functins used t simulate the water mvement. It turns ut that the time taken by these functins t calculate the result depends n the parameter passed t them. Fr numbers less than it takes mre r less 3.7 micrsecnds t calculate a sine r csine, whereas fr numbers higher that that it takes frm 41.3 t 42.7 micrsecnds. It is almst impssible t knw what is causing this behavir, as the underlying implementatin f these functins is nt public. Nevertheless, given the fact that is mre r less PI t the pwer f 64, it has was hinted in the Nkia frums that it might be due t hw lk-up tables are indexed in the implementatin. Frtunately, this prblem can be slved by nrmalizing the parameter passed t sinf() r csf() in an interval ranging frm zer t tw PI (r, mre generally, any range f the frm, where ). As this peratin takes nly frm 1.0 t 1.2 micrsecnds t execute, the result is that the scene is seen always at a gd speed. There are tw places where this prblem is shwed. One is in the CWaterSurfaceScenenNde class. In rder t fix it, the addwave() methd, defined in the file CWaterSurfaceSceneNde.h has t be changed t the fllwing: Page 195

196 vid addwave(cre::vectr3df& dest, cnst cre::vectr3df surce, f32 time) { f32 t1 = ((surce.x*onebywavelength) + time); f32 t2 = ((surce.z*onebywavelength) + time); t1 -= flrf(t1/twpi)*twpi; t2 -= flrf(t2/twpi)*twpi; } dest.y = surce.y + WaveHeight*( sinf(t1)+ csf(t2)); Cde 25. addwave() functin mdified s that the trignmetric functins exhibit their maximum perfrmance at all times. Where TwPI can be a variable r a macr with the value f tw multiplied by PI, that is, Other pssible slutin wuld have been t rewrite the frmula used fr the water mvement s that it des nt depend frm the time elapsed since the start f the applicatin but n the time elapsed since the last frame, as this ne is likely t remain less than the Hwever, the resulting frmula has tw sines and tw csines, intrducing an verhead higher than the prpsed slutin. The ther place where a similar prblem ccurs is in the CSceneNdeAnimatrFlyCircle class. There, the methd animatende(), defined in CSceneNdeAnimatrFlyCircle.cpp has t be changed t the fllwing: vid CSceneNdeAnimatrFlyCircle::animateNde(ISceneNde* nde, u32 timems) { if ( 0 == nde ) return; cnst f32 TwPI = 2*irr::cre::PI; f32 t = (timems-starttime) * Speed; t -= flrf(t/twpi)*twpi; } nde->setpsitin( Center + Radius * ((VecU*csf(t)) + (VecV*sinf(t))) ); Cde 26. animatende() functin mdified s that the trignmetric functins exhibit their maximum perfrmance. Page 196

197 6 RESULTS Nw that we have finished prting the engine, it is time t evaluate the result. In rder t test them, we will migrate the dem applicatins that cmes with the standard release and test their perfrmance n the N95 8GB. The fllwing sectins will explain hw we perfrmed bth tasks and the results btained. 6.1 PORTING THE DEMOS TO S60 In rder t test the Irrlicht Engine n the S60 3 rd Editin FP1 platfrm, we are ging t run the dems included in the standard release f the engine. These dems are designed t shw almst every feature f the engine, s they are almst enugh fr ur testing purpses. The fllwing sectins will explain hw t create the prject files fr the dems, and hw t change them s that they are cmpatible with the new. Finally, we will analyze the results f running them n the target device (the Nkia N95 8Gb) and evaluate thse results PROJECT FILES The first thing t d fr prting a dem is t create its prject in Carbide.c++, as it happened with the whle engine and, indeed, with mst prjects- this invlves the creatin f the same files as the in the case f the engine: the bld.inf file, and the MMP file. Hwever, since a dem is an applicatin that unlike a static library- is meant t be installed int the device, tw files mre are needed: a resurce file, and a pkg file. What fllws is a sample f thse files fr a given dem, alng with the relevant explanatins Bld.inf This is the cntent f the bld.inf file f the Quake3 Map dem. As it can be seen, it is quite trivial. PRJ_PLATFORMS DEFAULT PRJ_MMPFILES Quake3Map.mmp Cde 27. addwave() functin mdified s that the trignmetric functins exhibit their maximum perfrmance at all times MMP file 1 /* 2 ================================================================= 3 Name : Quake3Map.mmp 4 Authr : 5 Cpyright : 6 Descriptin : MMP file fr the Quake 3 Map dem f the Irrlicht Engine. 7 ================================================================= 8 */ Page 197

198 9 10 TARGET Quake3Map.exe 11 TARGETTYPE exe 12 UID 0x0 0xE SYSTEMINCLUDE \epc32\include\stdapis 15 SYSTEMINCLUDE \epc32\include 16 SYSTEMINCLUDE \epc32\include\stdapis\sys 17 SYSTEMINCLUDE \epc32\include\stdapis\stlprt LIBRARY libc.lib /* Fr standard C cmpatibility */ 20 LIBRARY libm.lib /* Fr maths */ 21 LIBRARY euser.lib /* Fr user */ 22 LIBRARY cne.lib /* Fr CCeEnv */ 23 LIBRARY ws32.lib /* Fr the Windw Server */ 24 LIBRARY ptiengine.lib /* Fr the PtiEngine */ 25 LIBRARY libgles_cm.lib /* Fr OpenGL ES */ STATICLIBRARY Irrlicht.lib /* Irrlicht Engine */ #ifdef EPOC32 30 LIBRARY libstdcpp.lib /* Fr standard C++ cmpatibility */ 31 #else 32 FIRSTLIB../udeb/libstdcpp.lib /* C++ cmpatibility in debug */ 33 STATICLIBRARY eexe.lib 34 MACRO _WCHAR_T_DECLARED 35 #endif //This is required even if the wchar type is nt used. 38 OPTION CW -wchar_t n USERINCLUDE \w\irr\include // Using main() as entry pint 44 STATICLIBRARY libcrt0.lib EPOCSTACKSIZE 0x EPOCHEAPSIZE 0x1000 0x #ifdef ENABLE_ABIV2_MODE 50 DEBUGGABLE 51 #endif SOURCEPATH.. 54 SOURCE symbutils.cpp Quake3Map.cpp 55 END 56 SOURCEPATH..\data 57 START RESOURCE Quake3Map_reg.rss 58 END Cde 28. MMP file fr the Quake 3 Map dem. Lines 10 t 12. These lines specify the name f the applicatin (Quake3Map.exe, in ur case), the target type (EXE, as we are building an executable) and the UID f the prgram. As we explained sme pages ag (cncretely in Creatin f the MMP file fr the static library, page 149), each element in Symbian has t have a unique UID. In ur case, this dem has the fllwing UID: Page 198

199 UID 1: It is implied that it is 0x A, at this is the value fr the EXE target. UID 2: We keep it as 0x0, as it is nt used fr the EXE target. UID 3: It has t be unique. We have develped the fllwing table fr the different Irrlicht dems: Dem UID 3 Hell Wrld 0xE Quake 3 Map 0xE Custm Scene Nde 0xE Mvement 0xE User Interface 0xE000132A 2D Graphics 0xE000132B Cllisin 0xE000132C Special FX 0xE000132D Mesh Viewer 0xE000132E Terrain Rendering 0xE000132F Render T Texture 0xE Lad Irr File 0xE Quake 3 Map Shader 0xE Nte that the UIDs have been chsen frm the develper range (0xExxxxxxx) as we are just perfrming testing. In rder t release these dems as nrmal applicatins, requesting a set f UIDs frm the 0xAxxxxxxx range t Symbian Signed 72 wuld be required. Lines 14 t 17. These lines specify the system include directries. These are the same files as in the Creatin f the MMP file fr the static library sectin (page 149). Lines 19 t 25. These lines tell which libraries against which link the cde resulting frm the cmpilatin. Line 27. This is the file that specifies that we have t link against the Irrlicht engine. Lines 29 t 35. These lines are required t supprt Open C++ in bth the GCC-E and the WINSCW cmpiler, accrding t the Open C++ dcumentatin. The first branch is meant t be executed when cmpiling fr the device, while the ther ne is meant t be executed when cmpiling fr the emulatr. In bth cases, what thse lines d is t tell the cmpiler hw t link against the Open C++ library. Line 38. This line defines a cmpilatin ptin fr the WINSCW cmpiler t include supprt fr wide characters (wchar_t), which are the Unicde cunterpart t the traditinal char type. Line 41. This line indicates the user include files. In ur case, we have t include the Irrlicht Engine include files nly. 72 Page 199

200 Line 44. This line indicates that the entry pint t the applicatin is the main() functin, instead f being the standard E32Main() f Symbian applicatins. Actually, what it des is just linking against a functin that seems t prvide a trivial E32Main() functin that calls the main() ne. Line 46. The default size f the stack f a prcess in Symbian OS v9.2 is just 8 kilbytes. That size has prven t be insufficient fr any large applicatin, and indeed it is recmmended in the Open C++ dcumentatin t increase it up t 64 kilbytes. Line 47. Just as it happens with the default stack size, it happens with the heap size. The default maximum heap size fr a user thread is 1 megabyte which is far less than we need, as we will lad mdels int memry larger than that. As the N95 8Gb has a maximum f 90 Mb f accessible RAM memry, we will set the maximum heap as 0x5A00000, and leave the minimum as the default. Lines 53 t 55. These lines specify which surce files have t be cmpiled. In ur case, the cpp f the applicatin and symbutils.cpp the utility file-. Lines 56 t 58. These lines specify the applicatin registratin file t be used. We will explain what this file is in the fllwing sectin Applicatin registratin file In cntrast with the static library we built fr the engine, nw we want t build an applicatin that wuld be able t be installed and run n the device. This means that the applicatin launcher and the system shell f the phne will need t have certain infrmatin abut the applicatin, such as its name, UID, icn and ther prperties. This infrmatin will be prvided by a file that will be installed (nce cmpiled) alng the applicatin, the s-called applicatin registratin file. Depending n what we want t d exactly use a custm icn r several, use ther lcalized resurces and s n- this file can be mre r less cmplex. Here, we will just shw the file needed fr the Quake 3 Map dem and explain it. Anyne interested in gaining a deeper understanding f this file, can just read the fficial dcumentatin at [105]. The fllwing cde shws a pssible file fr the dem: 1 #include <appinf.rh> 2 3 UID2 KUidAppRegistratinResurceFile 4 UID3 0xE RESOURCE APP_REGISTRATION_INFO 7 { 8 app_file="quake3map"; 9 embeddability=kappntembeddable; 10 newfile=kappdesntsupprtnewfile; 11 } Cde 29. Applicatin registratin file fr the Quake 3 Map dem (Quake3Map_reg.rss) Page 200

201 Line 1. Includes the header file that cntains the macrs and structures used in an applicatin registratin file. Lines 3 t 4. Indicate the UID 2 that is, the type- and the UID 3 f the applicatin resurce file. In this case, the cnstant KUidAppRegistratinResurceFile is used t specify that this is a resurce file, and the UID 3 f the dem applicatin is used the UID 3 f a applicatin registratin file must be the same as the UID 3 f the applicatin it is abut-. Lines 6 t 11. This is the main structure f the file, which cntains infrmatin abut the applicatin fr the System Shell and the Applicatin Launcher. In ur case, we have: Applicatin file (app_file). The name f the executable file f the applicatin, but withut the extensin. Embeddability (embeddability). Indicates whether the applicatin can be embedded int anther, which will nt be the case fr us. Fr mre infrmatin abut this tpic, please refer t [106] hwever, take int accunt that it is quite an ld resurce. Since its release, the AIF file has been supersedes by the Applicatin Registratin file. New File capability (newfile). Specifies whether the applicatin is dcumentbased and able t create new dcuments r nt. In ur case, it is nt. Fr mre infrmatin abut the pssible prperties f an applicatin refer t [107] PKG file Finally, we have t prvide a file called package file- that will guide Carbide.c++ t create the installatin file (a sisx file), which we will use later t install the dem applicatin n the phne. Just as it happens with the ther files, the cntent f this file can be mre r less difficult t understand and t read, these files have quite a cmplicated syntax-. What we will d here is t prvide a package file that can be used fr the Quake 3 Map dem and explained. Anyne wanting mre in-depth infrmatin abut these files can just refer t [108]. 1 ;Language - standard language definitins 2 &EN 3 4 ; standard SIS file header 5 #{"Quake 3 Map (Irrlicht dem)"},(0xe ),1,0,0 6 7 ;Lcalised Vendr name 8 %{""} 9 10 ;Unique Vendr name 11 :"" ;Supprts Series 60 v [0x101F7961], 0, 0, 0, {"Series60PrductID"} ;Files t install 17 "$(EPOCROOT)Epc32\release\$(PLATFORM)\$(TARGET)\Quake3Map.exe" - Page 201

202 "!:\sys\bin\quake3map.exe" 18 "$(EPOCROOT)Epc32\data\Quake3Map_reg.rsc" - "!:\private\10003a3f\imprt\apps\quake3map_reg.rsc" Cde 30. Package file fr the Quake 3 Map dem (Quake3Map.pkg) Lines 1 and 2. Specify the language f the applicatin. There can be mre than ne, but in ur case, we will just use the English language. Please, als nte that lines beginning with ; are cmments. Lines 4 and 5. They define the header f the package file. The frmat used is: #{ name f the applicatin },{UID 3 f it}, majr versin, minr versin and build number. There has t be as many applicatin names as languages specified in the line 2 in ur case, just ne-. Lines 7 t 11. The vendr name. The first string is the lcalized vendr name, and indeed there has t be ne per each language. The secnd string is a unique vendr name that will be used by Symbian signed t check whether the UID f the applicatin belngs t the persn requesting fr the sign. As we are nt releasing the applicatin as f nw- it is nt a cncern fr us. Lines 13 and 14. Hardware/platfrm dependency. When an applicatin is being installed, the installer prgram checks if this dependency is satisfied by the target phne. In ur case, we are specifying that ur applicatin requires the S60 3 rd Editin platfrm we believe we have nt used any feature exclusive f the Feature Pack 1-. The frmat f this line is: [package uid], versin-range, { cmpnent-name }. In ur case, the package UID is 0x101F7961, which crrespnds t the UID 3 f the S60 3 rd Editin platfrm see [109] fr a cmprehensive list f the pssible UIDs-, and its name is Series60PrductID. Lines 16 t 18. Files t be installed. In ur case we are installing tw files: The executable f the applicatin. The cmpiled applicatin registratin file. The!: drive letter in the path means that it has t be asked t the user at installatin time. It is wrth explaining the destinatin paths. Prir t Symbian OS 9.1, files culd be installed anywhere. Hwever, since that versin nwards, data caging impses strict restrictin abut which files can be installed where. Fr example, \sys\bin is the directry in which executable files have t be installed, and \private\10003a3f\imprt\apps is the directry in which applicatin registratin files have t. Fr mre infrmatin abut this, refer t the page available at [110] UTILITY FILES Nw that we have a prject ready t be mdified, cmpiled and its installer generated, we can begin. One f the advantages f having a crss-platfrm engine wuld be that the changes needed t d in an applicatin t migrate it t anther platfrm shuld be minimal. The Page 202

203 degree, in which this can be achieved, hwever, depends n the hetergeneity f thse platfrms; and S60 is quite different frm thse f the PC envirnment. Because f that reasn, there are sme changes that are needed t be dne in the cde f the dems. In rder t minimize, we will create tw utility files that we will call symbutils.c and symbutils.h- that will make changing a dem t be S60-cmpatible far mre easy. The fllwing lines will explain thse changes and hw t build helper functins fr them. It shuld be nted that this step is required t migrate the existing dems, which as re written in C++ and d nt use the Symbian applicatin framewrk. New dems specifically created fr S60 wuld nt need these files at all Initialize the Cntrl Envirnment In Creatin f a windw (page 161) we said that [The Cntrl Envirnment] is created autmatically by the framewrk and a pinter stred in Thread Lcal Strage (TLS). In the case f applicatins nt using the framewrk, it has t be explicitly created, hwever. By the time we talked abut it we did nt have t wrry abut that, because it is nw, at the applicatin level, when we need t take care f it. As the Irrlicht dems includes with the standard package d nt use the applicatin framewrk fr bvius reasns- we can either mdify them t use it which wuld be a massive mdificatin- r just initialize the Cntrl Envirnment urselves. The secnd ptin is the ne we have chsen. In rder t facilitate this task t the user, and t minimize the changes t be dne inside the existing dem cde, we will create a functin called initializecntrlenvirnmentl() when it cmes t assign names t functins riginality is nt a virtue- that will perfrm this tasks. The cde f this functin shuld be smething similar t: // Creates the Cntrl envirnment CCeEnv* env = new (ELeave) CCeEnv(); TRAPD( err, env->cnstructl( ETrue, 0 ) ); //Set a new Active Scheduler delete CActiveScheduler::Current(); CActiveScheduler* actscheduler = new (ELeave) CActiveScheduler(); CActiveScheduler::Install( actscheduler ); Cde 31. Cde needed t initialize the Cntrl Envirnment. The cde wuld be self-explanatry fr sme familiar with Symbian prgramming, but we will explain it fr thse that are nt. The first tw lines perfrm a tw-phase cnstructin. The new peratr called is a special versin defined in Symbian, that leaves raises the Symbian equivalent t an exceptin- if there is nt enugh memry. TRAPD, n the ther hand, is just a pre-defined macr that stres in the variable passed as the first parameter -err, in ur case- the errr value resulting frm executing the secnd parameter in ur case, the secnd phase cnstructr-. Page 203

204 Cnstructing the Cntrl Envirnment autmatically creates an active scheduler and adds tw active bjects t it, fr managing standard and re-draw events (see [111] fr mre details). As we will prvide ur wn Active Object in the engine, the best we can d fr deleting thse undesired nes is t delete the current Active Scheduler and create a new ne; exactly what is dne in the rest f the cde. Please nt that after creating the scheduler, it has t be set as the current scheduler fr the thread by using the Install methd (refer t [112] fr mre infrmatin abut it) Destry the Cntrl Envirnment As we have manually created the Cntrl Envirnment, we have t destry it befre the applicatin exists. Fr this reasn, we will prvide a functin called destrycntrlenvirnment() in the symbutils.c and symbutils.h files. The cde f that functin will be quite easy: CCeEnv::Static()->DestryEnvirnment(); delete CCeEnv::Static(); Cde 32. Cde fr destrying the Cntrl Envirnment Prcess Backgrund tasks When we explained the Active Object pattern, we stated that it implements cperative multitasking inside the thread f the applicatin. That means that, smewhere in that thread, we have t pass the cntrl t the Active Scheduler s that it can execute the RunL methd f the ActiveObject whse request has already been attended. The best place t d s is at the beginning f the main lp. Because f that reasn, we will prvide a functin in the utility files, called prcessbackgrundtasks() that will d exactly that, and will be meant t be called inside the main lp f the applicatin. The cde needed fr this functin is: RThread thread; TInt errr = KErrNne; // Prcesses all utstanding requests while( thread.requestcunt() ) { // Prcesses an event. CActiveScheduler::RunIfReady( errr, CActive::EPrirityIdle ); // Decreases thread.requestcunt User::WaitFrAnyRequest(); } Cde 33. Cde needed t let the Active Scheduler calling the RunL methd f the Active Objects whse request has been cmpleted. This is called the Cntrl Lp f the scheduler. Page 204

205 What this cde des is the fllwing: It gets the semaphre f the thread used fr cunting the number f cmpleted requests, by using the RequestCunt() methd. If the result is psitive, it means that at least ne asynchrnus request has been cmpleted, and s the Active Scheduler is called t run n Active Object that has t be run, by using the RunIfReady() methd. After ding s, the WaitFrAnyRequest() methd updates the semaphre. Return t step ne. Refer t [112] and [113] fr mre details DEMO MODIFICATIONS Nw that we have defined thse functins, it is time t mdify the dems we want t run in the mbile phne. As mre r less they will be mdified in the same way, we will just cmment the mdified versin f the Quake 3 Map dem. The fllwing cde sectin will shw hw the mdified surce cde fr the dem (changes highlighted in yellw, cmment blcks remved). #include <irrlicht.h> #ifdef _IRR_SYMBIAN_ include "symbutils.h" #endif #include <istream> using namespace irr; #pragma cmment(lib, "Irrlicht.lib") int main() { #ifdef _IRR_SYMBIAN_ initializecntrlenvirnmentl(); chdir("e:/irrlicht/dummy/dummy"); #endif // ask user fr driver vide::e_driver_type drivertype = vide::edt_direct3d9; printf("please select the driver yu want fr this example:\n"\ " (a) Direct3D 9.0c\n (b) Direct3D 8.1\n (c) OpenGL 1.5\n"\ " (d) OpenGL ES 1.1\n (e) Sftware Renderer\n"\ " (f) Burning Sftware Renderer\n"\ " (g) NullDevice\n (therkey) exit\n\n"); char i; std::cin >> i; switch(i) { case 'a': drivertype = vide::edt_direct3d9;break; case 'b': drivertype = vide::edt_direct3d8;break; case 'c': drivertype = vide::edt_opengl; break; Page 205

206 } case 'd': drivertype = vide::edt_opengles; break; case 'e': drivertype = vide::edt_software; break; case 'f': drivertype = vide::edt_burningsvideo;break; case 'g': drivertype = vide::edt_null; break; default: return 1; // create device and exit if creatin failed IrrlichtDevice *device = createdevice(drivertype, cre::dimensin2d<s32>(640, 480), 16, true); if (device == 0) return 1; // culd nt create selected driver. vide::ividedriver* driver = device->getvidedriver(); scene::iscenemanager* smgr = device->getscenemanager(); device->getfilesystem()->addzipfilearchive("../../media/map- 20kdm2.pk3"); scene::ianimatedmesh* mesh = smgr->getmesh("20kdm2.bsp"); scene::iscenende* nde = 0; 128); if (mesh) nde = smgr->addocttreescenende(mesh->getmesh(0), 0, -1, if (nde) nde->setpsitin(cre::vectr3df(-1300,-144,-1249)); smgr->addcamerascenendefps(); device->getcursrcntrl()->setvisible(false); int lastfps = -1; while(device->run()) { #ifdef _IRR_SYMBIAN_ prcessbackgrundtasks(); #endif if (device->iswindwactive()) { device->beginscene(true, true, vide::sclr(0,200,200,200)); smgr->drawall(); device->endscene(); int fps = driver->getfps(); if (lastfps!= fps) { cre::stringw str = L"Irrlicht Engine - Quake 3 Map example ["; str += driver->getname(); str += "] FPS:"; str += fps; Page 206

207 } } device->setwindwcaptin(str.c_str()); lastfps = fps; } device->drp(); #ifdef _IRR_SYMBIAN_ destrycntrlenvirnment(); #endif return 0; } Cde 34. Standard key bindings fr different actins in Irrlicht. We can see that the changes required have been: Including the utility files. Calling initializecntrlenvirnmentl() at the beginning f the applicatin. Setting a fake current directry. This is needed because the Irrlicht dems assume t be installed in tw directries lwer in the hierarchy than the media directry where the mdels are. This is nt true in Symbian. Adding the OpenGL ES 1.1 driver as a pssible ptin fr the user. Actually, althugh the usually will be able t select any ther, this is the nly pssible ne fr the S60 platfrm. Setting the ptin at the device creatin t have a full-screen windw. The desired ne in ther platfrms is a 640x480 windw, which is smaller than pssible in the N95 8GB. Because f that reasn, the best ptin is t make the windw full-screen. Adding a call t prcessbackgrundtasks() at the beginning f the main lp. Adding a call t destrycntrlenvirnment() befre exiting the applicatin. Althugh these changes are the base nes, sme ther might be needed depending n the dem. Fr example, in the GUI dem, the psitins f the elements shuld be changed t fit int the smaller screen f the N95 mbile phne. In additin t that, in applicatins using a custm User Receiver, it might be a gd t ensure that there is nw distinctin between key press and release events, as in multi-tapping mde bth are sent each time a character is fixed. 6.2 RUNNING THE DEMOS ON THE N95 8GB After adapting all the dems, it is nw pssible t run them n the device. The fllwing lines will shw hw many frame per secnd they are able t achieve, which features are missing n the phne and, definitely, which are the differences between running them n a PC envirnment r in the mbile. In rder t be able t analyze the results, the specificatins f the cmputer used fr the test is needed, s here this data is: Page 207

208 Hardware infrmatin Prcessr: Intel Cre 2 Quad 6600 (4 cres at 2.4GHz each) Memry: 4 GB f DDR2 RAM (nly 3.25 GB addressable) Graphics card Vendr: Gainward Chip type: NVidia GeFrce 8800 GTX Bus type: PCI Express 16x/16x VGA memry: 768.0MB Sftware infrmatin Operating system: Micrsft Windws XP Prfessinal, SP 2 (Build 2600) Driver infrmatin Graphics driver: FrceWare Direct 3D versin: OpenGL versin: Finally, we wuld like t pint ut that the screenshts f the dems running n the mbile phne are actual screenshts taken using the functinality prvided by the Irrlicht engine and later retrieved frm the phne. This ffers much mre quality than taking a phtgraph f the actual device, and allws us, by the way, t check that the screensht functinality wrks perfectly. Als nte that the muse pinter is nt captured in Windws, but it is the mbile phne. Page 208

209 6.2.1 HELLO WORLD Applicatin size: 2300 KB. Frames per secnd: Direct 3D 9 OpenGL OpenGL ES CM New features tested: Feature Status Cmments MD2 file lader Wrking fine. Mixed 3D graphics and GUI Wrking fine. Animatin Wrking fine. Muse emulatin Wrking fine. Page 209

210 6.2.2 QUAKE 3 MAP Applicatin size: 2300 KB. Frames per secnd: Direct 3D 9 OpenGL OpenGL ES CM New features tested: Feature Status Cmments Quake 3 map lader Wrking fine. Huge number f plygns Wrking fine. Multi-texture Wrking fine. See the illuminatin f the trches. FPS camera Wrking fine. Hidden muse pinter Wrking fine. Further cmments: Due t flating-pint accuracy issues, sme artifacts appear smetimes in the jint f the triangles when they are far frm the camera. This can be seen, fr example, in the tp f the building near the 1.1 versin number, in the OpenGL ES CM 1.1 image. These artifacts, hwever, are f minr imprtance, since they just appear in sme frames and d nt affect the image glbally. Page 210

211 6.2.3 USER INTERFACE Applicatin size: 2304 KB. Frames per secnd: Direct 3D 9 OpenGL OpenGL ES CM New features tested: Feature Status Cmments All GUI elements Wrking fine. GUI withut 3D graphics Wrking fine. File system Wrking fine. See the tp windw. All input methds It cannt be seen in the image, but they all wrk fine. Page 211

212 D GRAPHICS Applicatin size: 2301 KB. Frames per secnd: Direct 3D 9 OpenGL OpenGL ES CM New features tested: Feature Status Cmments Direct usage f the vide driver Wrking fine. The vide driver is used directly fr rendering the 2D graphics, withut the Scene Manager r the GUI envirnment. Obtaining f the pinter psitin The semi-transparent square is shwn at the pinter psitin. Clr key The alpha channel f the images shwn is calculated by the vide driver. Page 212

The Importance Advanced Data Collection System Maintenance. Berry Drijsen Global Service Business Manager. knowledge to shape your future

The Importance Advanced Data Collection System Maintenance. Berry Drijsen Global Service Business Manager. knowledge to shape your future The Imprtance Advanced Data Cllectin System Maintenance Berry Drijsen Glbal Service Business Manager WHITE PAPER knwledge t shape yur future The Imprtance Advanced Data Cllectin System Maintenance Cntents

More information

Licensing Windows Server 2012 R2 for use with virtualization technologies

Licensing Windows Server 2012 R2 for use with virtualization technologies Vlume Licensing brief Licensing Windws Server 2012 R2 fr use with virtualizatin technlgies (VMware ESX/ESXi, Micrsft System Center 2012 R2 Virtual Machine Manager, and Parallels Virtuzz) Table f Cntents

More information

Licensing Windows Server 2012 for use with virtualization technologies

Licensing Windows Server 2012 for use with virtualization technologies Vlume Licensing brief Licensing Windws Server 2012 fr use with virtualizatin technlgies (VMware ESX/ESXi, Micrsft System Center 2012 Virtual Machine Manager, and Parallels Virtuzz) Table f Cntents This

More information

Improved Data Center Power Consumption and Streamlining Management in Windows Server 2008 R2 with SP1

Improved Data Center Power Consumption and Streamlining Management in Windows Server 2008 R2 with SP1 Imprved Data Center Pwer Cnsumptin and Streamlining Management in Windws Server 2008 R2 with SP1 Disclaimer The infrmatin cntained in this dcument represents the current view f Micrsft Crpratin n the issues

More information

Disk Redundancy (RAID)

Disk Redundancy (RAID) A Primer fr Business Dvana s Primers fr Business series are a set f shrt papers r guides intended fr business decisin makers, wh feel they are being bmbarded with terms and want t understand a cmplex tpic.

More information

Software and Hardware Change Management Policy for CDes Computer Labs

Software and Hardware Change Management Policy for CDes Computer Labs Sftware and Hardware Change Management Plicy fr CDes Cmputer Labs Overview The cmputer labs in the Cllege f Design are clsely integrated with the academic needs f faculty and students. Cmputer lab resurces

More information

Level 1 Technical. RealPresence Web Suite and Web Suite Pro. Contents

Level 1 Technical. RealPresence Web Suite and Web Suite Pro. Contents Level 1 Technical RealPresence Web Suite and Web Suite Pr Cntents 1 - Glssary... 2 2 Features... 3 RealPresence Platfrm integratin... 3 RealPresence Web Suite Sftware... 3 Sftware Keys... 3 3 - Web Client

More information

To transform information into knowledge- a firm must expend additional resources to discover, patterns, rules, and context where the knowledge works

To transform information into knowledge- a firm must expend additional resources to discover, patterns, rules, and context where the knowledge works Chapter 15- Managing Knwledge Knwledge Management Landscape Knwledge management systems- supprt the creatin, capture, strage, and disseminatin f firm expertise and knwledge, have becme ne f the fastest-grwing

More information

Sample Role Description Immunization Information System (IIS) Testing Analyst

Sample Role Description Immunization Information System (IIS) Testing Analyst Sample Rle Descriptin Immunizatin Infrmatin System (IIS) Testing Analyst Nte: This rle descriptin is meant t ffer sample language and a cmprehensive list f ptential desired respnsibilities with crrespnding

More information

Design for securability Applying engineering principles to the design of security architectures

Design for securability Applying engineering principles to the design of security architectures Design fr securability Applying engineering principles t the design f security architectures Amund Hunstad Phne number: + 46 13 37 81 18 Fax: + 46 13 37 85 50 Email: Jnas Hallberg Phne number:

More information

CSE 231 Fall 2015 Computer Project #4

CSE 231 Fall 2015 Computer Project #4 CSE 231 Fall 2015 Cmputer Prject #4 Assignment Overview This assignment fcuses n the design, implementatin and testing f a Pythn prgram that uses character strings fr data decmpressin. It is wrth 45 pints

More information

Licensing the Core Client Access License (CAL) Suite and Enterprise CAL Suite

Licensing the Core Client Access License (CAL) Suite and Enterprise CAL Suite Vlume Licensing brief Licensing the Cre Client Access License (CAL) Suite and Enterprise CAL Suite Table f Cntents This brief applies t all Micrsft Vlume Licensing prgrams. Summary... 1 What s New in This

More information

Service Desk Self Service Overview

Service Desk Self Service Overview Tday s Date: 08/28/2008 Effective Date: 09/01/2008 Systems Invlved: Audience: Tpics in this Jb Aid: Backgrund: Service Desk Service Desk Self Service Overview All Service Desk Self Service Overview Service

More information

Change Management Process

Change Management Process Change Management Prcess B1.10 Change Management Prcess 1. Intrductin This plicy utlines [Yur Cmpany] s apprach t managing change within the rganisatin. All changes in strategy, activities and prcesses

More information

1)What hardware is available for installing/configuring MOSS 2010?

1)What hardware is available for installing/configuring MOSS 2010? 1)What hardware is available fr installing/cnfiguring MOSS 2010? 2 Web Frnt End Servers HP Prliant DL 380 G7 2 quad cre Intel Xen Prcessr E5620, 2.4 Ghz, Memry 12 GB, 2 HP 146 GB drives RAID 5 2 Applicatin

More information

Getting started with Android

Getting started with Android Getting started with Andrid Befre we begin, there is a prerequisite, which is t plug the Andrid device int yur cmputer, and lad the drivers fr the OS. In writing this article, I was using Windws XP, 7

More information

How Does Cloud Computing Work?

How Does Cloud Computing Work? Hw Des Clud Cmputing Wrk? Carl Mazzanti, CEO, emazzanti Technlgies IT Supprt and Clud Cmputing Services fr Small Business Hbken, NJ and NYC, 201-360- 4400 Owner [Pick the date] Hw des Clud Cmputing Wrk?

More information

HarePoint HelpDesk for SharePoint. For SharePoint Server 2010, SharePoint Foundation 2010. User Guide

HarePoint HelpDesk for SharePoint. For SharePoint Server 2010, SharePoint Foundation 2010. User Guide HarePint HelpDesk fr SharePint Fr SharePint Server 2010, SharePint Fundatin 2010 User Guide Prduct versin: 14.1.0 04/10/2013 2 Intrductin HarePint.Cm (This Page Intentinally Left Blank ) Table f Cntents

More information



More information

Integrate Marketing Automation, Lead Management and CRM

Integrate Marketing Automation, Lead Management and CRM Clsing the Lp: Integrate Marketing Autmatin, Lead Management and CRM Circular thinking fr marketers 1 (866) 372-9431 Clsing the Lp: Integrate Marketing Autmatin, Lead Management

More information

Success in Mathematics

Success in Mathematics Success in Mathematics Tips n hw t study mathematics, hw t apprach prblem-slving, hw t study fr and take tests, and when and hw t get help. Math Study Skills Be actively invlved in managing the learning

More information

Serv-U Distributed Architecture Guide

Serv-U Distributed Architecture Guide Serv-U Distributed Architecture Guide Hrizntal Scaling and Applicatin Tiering fr High Availability, Security, and Perfrmance Serv-U Distributed Architecture Guide v14.0.1.0 Page 1 f 16 Intrductin Serv-U

More information


NOVA COLLEGE-WIDE COURSE CONTENT SUMMARY ITE 170 - MULTIMEDIA SOFTWARE (3 CR.) Revised 8/2012 NOVA COLLEGE-WIDE COURSE CONTENT SUMMARY ITE 170 - MULTIMEDIA SOFTWARE (3 CR.) Curse Descriptin Explres technical fundamentals f creating multimedia prjects with related hardware and sftware.

More information

SBClient and Microsoft Windows Terminal Server (Including Citrix Server)

SBClient and Microsoft Windows Terminal Server (Including Citrix Server) SBClient and Micrsft Windws Terminal Server (Including Citrix Server) Cntents 1. Intrductin 2. SBClient Cmpatibility Infrmatin 3. SBClient Terminal Server Installatin Instructins 4. Reslving Perfrmance

More information


CDC UNIFIED PROCESS PRACTICES GUIDE Dcument Purpse The purpse f this dcument is t prvide guidance n the practice f Risk Management and t describe the practice verview, requirements, best practices, activities, and key terms related t these

More information

PART 6. Chapter 12. How to collect and use feedback from readers. Should you do audio or video recording of your sessions?

PART 6. Chapter 12. How to collect and use feedback from readers. Should you do audio or video recording of your sessions? TOOLKIT fr Making Written Material Clear and Effective SECTION 3: Methds fr testing written material with readers PART 6 Hw t cllect and use feedback frm readers Chapter 12 Shuld yu d audi r vide recrding

More information

This report provides Members with an update on of the financial performance of the Corporation s managed IS service contract with Agilisys Ltd.

This report provides Members with an update on of the financial performance of the Corporation s managed IS service contract with Agilisys Ltd. Cmmittee: Date(s): Infrmatin Systems Sub Cmmittee 11 th March 2015 Subject: Agilisys Managed Service Financial Reprt Reprt f: Chamberlain Summary Public Fr Infrmatin This reprt prvides Members with an

More information

Information Services Hosting Arrangements

Information Services Hosting Arrangements Infrmatin Services Hsting Arrangements Purpse The purpse f this service is t prvide secure, supprted, and reasnably accessible cmputing envirnments fr departments at DePaul that are in need f server-based

More information

ATL: Atlas Transformation Language. ATL Installation Guide

ATL: Atlas Transformation Language. ATL Installation Guide ATL: Atlas Transfrmatin Language ATL Installatin Guide - versin 0.1 - Nvember 2005 by ATLAS grup LINA & INRIA Nantes Cntent 1 Intrductin... 3 2 Installing ADT frm binaries... 3 2.1 Installing Eclipse and

More information

Research Report. Abstract: The Emerging Intersection Between Big Data and Security Analytics. November 2012

Research Report. Abstract: The Emerging Intersection Between Big Data and Security Analytics. November 2012 Research Reprt Abstract: The Emerging Intersectin Between Big Data and Security Analytics By Jn Oltsik, Senir Principal Analyst With Jennifer Gahm Nvember 2012 2012 by The Enterprise Strategy Grup, Inc.

More information

Dec. 2012. Transportation Management System. An Alternative Traffic Solution for the Logistics Professionals

Dec. 2012. Transportation Management System. An Alternative Traffic Solution for the Logistics Professionals Dec. 2012 Transprtatin Management System An Alternative Traffic Slutin fr the Lgistics Prfessinals What is a TMS-Lite system? What are the features and capabilities f a TMS-Lite system? Why chse a TMS-Lite

More information

Why Can t Johnny Encrypt? A Usability Evaluation of PGP 5.0 Alma Whitten and J.D. Tygar

Why Can t Johnny Encrypt? A Usability Evaluation of PGP 5.0 Alma Whitten and J.D. Tygar Class Ntes: February 2, 2006 Tpic: User Testing II Lecturer: Jeremy Hyland Scribe: Rachel Shipman Why Can t Jhnny Encrypt? A Usability Evaluatin f PGP 5.0 Alma Whitten and J.D. Tygar This article has three

More information

Web Development the Next Steps

Web Development the Next Steps Web Develpment the Next Steps Significant prgress has been made n the redesign f the Western Washingtn University hme page. The ATUS Web Services team has wrked hard in cllabratin with the University Cmmunicatins

More information

Helpdesk Support Tickets & Knowledgebase

Helpdesk Support Tickets & Knowledgebase Helpdesk Supprt Tickets & Knwledgebase User Guide Versin 1.0 Website: Supprt: Please read this user guide carefully, it will help yu eliminate

More information

Support Services. v1.19 / 2015-07-02

Support Services. v1.19 / 2015-07-02 Supprt Services v1.19 / 2015-07-02 Intrductin - Table f Cntents 1 Intrductin... 3 2 Definitins... 4 3 Supprt Prgram Feature Overview... 5 4 SLA fr the Supprt Services... 6 4.1 Standard Supprt... 6 4.2

More information

Version: Modified By: Date: Approved By: Date: 1.0 Michael Hawkins October 29, 2013 Dan Bowden November 2013

Version: Modified By: Date: Approved By: Date: 1.0 Michael Hawkins October 29, 2013 Dan Bowden November 2013 Versin: Mdified By: Date: Apprved By: Date: 1.0 Michael Hawkins Octber 29, 2013 Dan Bwden Nvember 2013 Rule 4-004J Payment Card Industry (PCI) Patch Management (prpsed) 01.1 Purpse The purpse f the Patch

More information

HP ExpertOne. HP2-T21: Administering HP Server Solutions. Table of Contents

HP ExpertOne. HP2-T21: Administering HP Server Solutions. Table of Contents HP ExpertOne HP2-T21: Administering HP Server Slutins Industry Standard Servers Exam preparatin guide Table f Cntents Overview 2 Why take the exam? 2 HP ATP Server Administratr V8 certificatin 2 Wh shuld

More information

Succession Planning & Leadership Development: Your Utility s Bridge to the Future

Succession Planning & Leadership Development: Your Utility s Bridge to the Future Successin Planning & Leadership Develpment: Yur Utility s Bridge t the Future Richard L. Gerstberger, P.E. TAP Resurce Develpment Grup, Inc. 4625 West 32 nd Ave Denver, CO 80212 ABSTRACT A few years ag,

More information

Mobile Workforce. Improving Productivity, Improving Profitability

Mobile Workforce. Improving Productivity, Improving Profitability Mbile Wrkfrce Imprving Prductivity, Imprving Prfitability White Paper The Business Challenge Between increasing peratinal cst, staff turnver, budget cnstraints and pressure t deliver prducts and services

More information

Importance and Contribution of Software Engineering to the Education of Informatics Professionals

Importance and Contribution of Software Engineering to the Education of Informatics Professionals Imprtance and Cntributin f Sftware Engineering t the Educatin f Infrmatics Prfessinals Dr. Tick, József Budapest Plytechnic, Hungary, Abstract: As a result f the Blgna prcess a new frm f higher

More information

Service Level Agreement (SLA) Hosted Products. Netop Business Solutions A/S

Service Level Agreement (SLA) Hosted Products. Netop Business Solutions A/S Service Level Agreement (SLA) Hsted Prducts Netp Business Slutins A/S Cntents 1 Service Level Agreement... 3 2 Supprt Services... 3 3 Incident Management... 3 3.1 Requesting service r submitting incidents...

More information

Getting Started Guide

Getting Started Guide AnswerDash Resurces Cntextual help fr sales and supprt Getting Started Guide AnswerDash is cmmitted t helping yu achieve yur larger business gals. The utlined pre-launch cnsideratins

More information

Diagnosis and Troubleshooting

Diagnosis and Troubleshooting Diagnsis and Trubleshting DataDirect Cnnect Series ODBC Drivers Intrductin This paper discusses the diagnstic tls that are available t cnfigure and trublesht yur ODBC envirnment and prvides a trubleshting

More information

Syllabus Computer Science III: Data Structures and Algorithms Fall 2012 COMP 241 CRN: 13761

Syllabus Computer Science III: Data Structures and Algorithms Fall 2012 COMP 241 CRN: 13761 Syllabus Cmputer Science III: Data Structures and Algrithms Fall 2012 COMP 241 CRN: 13761 Basic Inf: Instructr: Tuesday/Thursday, 11:00am 12:15pm Buckman 222 Betsy (Williams) Sanders Office: Olendrf 419

More information

2008 BA Insurance Systems Pty Ltd

2008 BA Insurance Systems Pty Ltd 2008 BA Insurance Systems Pty Ltd BAIS have been delivering insurance systems since 1993. Over the last 15 years, technlgy has mved at breakneck speed. BAIS has flurished in this here tday, gne tmrrw sftware

More information

System Business Continuity Classification

System Business Continuity Classification Business Cntinuity Prcedures Business Impact Analysis (BIA) System Recvery Prcedures (SRP) System Business Cntinuity Classificatin Cre Infrastructure Criticality Levels Critical High Medium Lw Required

More information

Best Practice - Pentaho BA for High Availability

Best Practice - Pentaho BA for High Availability Best Practice - Pentah BA fr High Availability This page intentinally left blank. Cntents Overview... 1 Pentah Server High Availability Intrductin... 2 Prerequisites... 3 Pint Each Server t Same Database

More information

METU. Computer Engineering

METU. Computer Engineering METU Cmputer Engineering CENG 491 Cmputer Engineering Design I AKAMAI SYSTEMS Members f the Team: Ahmet Emin Tsun Uğur Can Tekin Hasan İşler

More information

Business Intelligence represents a fundamental shift in the purpose, objective and use of information

Business Intelligence represents a fundamental shift in the purpose, objective and use of information Overview f BI and rle f DW in BI Business Intelligence & Why is it ppular? Business Intelligence Steps Business Intelligence Cycle Example Scenaris State f Business Intelligence Business Intelligence Tls

More information

D11.6 Project Web Site Report

D11.6 Project Web Site Report Grant Agreement Number 216487 Integrated Cgnitive Assistive & Dmtic Cmpanin Rbtic Systems fr Ability & Security Cllabrative Prject ICT-2007.7.1 ICT and ageing published by the CmpaninAble Cnsrtium Versin:

More information

Cornwall Partners in Care

Cornwall Partners in Care Crnwall Partners in Care Mving Frward Versin 2.0 8 th January 2014 By Richard Mnk Crnwall Partners in Care August 2013 Page 1 f 6 CPIC mving frward This dcument has been created t help prvide a little

More information

March 2016 Group A Payment Issues: Missing Information-Loss Calculation letters ( MILC ) - deficiency resolutions: Outstanding appeals:

March 2016 Group A Payment Issues: Missing Information-Loss Calculation letters ( MILC ) - deficiency resolutions: Outstanding appeals: The fllwing tpics were discussed in the March 24, 2016 meeting with law firms representing VCF claimants. Grup A Payment Issues: We cntinue t fcus n paying Grup A claims in full and are meeting the schedule

More information

Knowledge Base Article

Knowledge Base Article Knwledge Base Article Crystal Matrix Interface Cmparisn TCP/IP vs. SDK Cpyright 2008-2012, ISONAS Security Systems All rights reserved Table f Cntents 1: INTRODUCTION... 3 1.1: TCP/IP INTERFACE OVERVIEW:...

More information

Implementing an electronic document and records management system using SharePoint 7

Implementing an electronic document and records management system using SharePoint 7 Reprt title Agenda item Implementing an electrnic dcument and recrds management system using SharePint 7 Meeting Finance, Prcurement & Prperty Cmmittee 16 June 2008 Date Reprt by Dcument Number Head f

More information

Application Note: 202

Application Note: 202 Applicatin Nte: 202 MDK-ARM Cmpiler Optimizatins Getting the Best Optimized Cde fr yur Embedded Applicatin Abstract This dcument examines the ARM Cmpilatin Tls, as used inside the Keil MDK-ARM (Micrcntrller

More information

FOCUS Service Management Software Version 8.5 for CounterPoint Installation Instructions

FOCUS Service Management Software Version 8.5 for CounterPoint Installation Instructions FOCUS Service Management Sftware Versin 8.5 fr CunterPint Installatin Instructins Thank yu fr purchasing Fcus Service Management Sftware frm RTM Cmputer Slutins. This bklet f installatin instructins will

More information

Migrating to SharePoint 2010 Don t Upgrade Your Mess

Migrating to SharePoint 2010 Don t Upgrade Your Mess Migrating t SharePint 2010 Dn t Upgrade Yur Mess by David Cleman Micrsft SharePint Server MVP April 2011 Phne: (610)-717-0413 Email: Website: Intrductin May 12 th

More information

Access EEC s Web Applications... 2 View Messages from EEC... 3 Sign In as a Returning User... 3

Access EEC s Web Applications... 2 View Messages from EEC... 3 Sign In as a Returning User... 3 EEC Single Sign In (SSI) Applicatin The EEC Single Sign In (SSI) Single Sign In (SSI) is the secure, nline applicatin that cntrls access t all f the Department f Early Educatin and Care (EEC) web applicatins.

More information

Completing the CMDB Circle: Asset Management with Barcode Scanning

Completing the CMDB Circle: Asset Management with Barcode Scanning Cmpleting the CMDB Circle: Asset Management with Barcde Scanning WHITE PAPER The Value f Barcding Tday, barcdes are n just abut everything manufactured and are used fr asset tracking and identificatin

More information

Systems Support - Extended

Systems Support - Extended 1 General Overview This is a Service Level Agreement ( SLA ) between and the Enterprise Windws Services t dcument: The technlgy services the Enterprise Windws Services prvides t the custmer. The targets

More information



More information

White Paper for Mobile Workforce Management and Monitoring Copyright 2014 by Patrol-IT Inc.

White Paper for Mobile Workforce Management and Monitoring Copyright 2014 by Patrol-IT Inc. White Paper fr Mbile Wrkfrce Management and Mnitring Cpyright 2014 by Patrl-IT Inc. White Paper fr Mbile Wrkfrce Management and Mnitring Cpyright 2014 by Patrl-IT Inc. 2

More information

The Lunchtime Guide to Student Blogging: By Anand Ramchand

The Lunchtime Guide to Student Blogging: By Anand Ramchand Technlgy in Pedaggy, N. 2 The Lunchtime Guide t Student Blgging: By Anand Ramchand Technlgy in Pedaggy, N. 2, April 2011 Written by Kiruthika Ragupathi ( Anand Ramchand, an Instructr

More information

Gartner Magic Quadrant Salesforce Automation 2009

Gartner Magic Quadrant Salesforce Automation 2009 Gartner Magic Quadrant Salesfrce Autmatin 2009 Sage CRM Slutins Opinin Brief Released July 24, 2009 Q. What is the Gartner Magic Quadrant (GMQ) fr SFA? A. The Gartner Magic Quadrant fr SFA is an analyst

More information

Best Practices for Optimizing Performance and Availability in Virtual Infrastructures

Best Practices for Optimizing Performance and Availability in Virtual Infrastructures Best Practices fr Optimizing Perfrmance and Availability in Virtual Infrastructures Best Practices fr Optimizing Perfrmance and Availability in Virtual Infrastructures PAGE 2 Table f Cntents

More information

LeadStreet Broker Guide

LeadStreet Broker Guide RE/MAX f Western Canada LeadStreet Brker Guide Ver. 2.0 Revisin Histry Name Date Versin Descriptin Tamika Anglin 09/04/13 1.0 Initial Creatin Tamika Anglin 11/05/13 2.0 Inclusin f instructins n reprting

More information

Preparing to Deploy Reflection : A Guide for System Administrators. Version 14.1

Preparing to Deploy Reflection : A Guide for System Administrators. Version 14.1 Preparing t Deply Reflectin : A Guide fr System Administratrs Versin 14.1 Table f Cntents Table f Cntents... 2 Preparing t Deply Reflectin 14.1:... 3 A Guide fr System Administratrs... 3 Overview f the

More information

Copyrights and Trademarks

Copyrights and Trademarks Cpyrights and Trademarks Sage One Accunting Cnversin Manual 1 Cpyrights and Trademarks Cpyrights and Trademarks Cpyrights and Trademarks Cpyright 2002-2014 by Us. We hereby acknwledge the cpyrights and

More information

BRILL s Editorial Manager (EM) Manual for Authors Table of Contents

BRILL s Editorial Manager (EM) Manual for Authors Table of Contents BRILL s Editrial Manager (EM) Manual fr Authrs Table f Cntents Intrductin... 2 1. Getting Started: Creating an Accunt... 2 2. Lgging int EM... 3 3. Changing Yur Access Cdes and Cntact Infrmatin... 3 3.1

More information


THE CUSTOMER SUPPORT KNOWLEDGE BASE FAQ THE CUSTOMER SUPPORT KNOWLEDGE BASE FAQ What is the Knwledge Base? - The Knwledge Base (r KB) is a searchable database in which different dcument types f technical dcumentatin are aggregated. These vary

More information

System Business Continuity Classification

System Business Continuity Classification System Business Cntinuity Classificatin Business Cntinuity Prcedures Infrmatin System Cntingency Plan (ISCP) Business Impact Analysis (BIA) System Recvery Prcedures (SRP) Cre Infrastructure Criticality

More information

Implementing SQL Manage Quick Guide

Implementing SQL Manage Quick Guide Implementing SQL Manage Quick Guide The purpse f this dcument is t guide yu thrugh the quick prcess f implementing SQL Manage n SQL Server databases. SQL Manage is a ttal management slutin fr Micrsft SQL

More information

Implementing ifolder Server in the DMZ with ifolder Data inside the Firewall

Implementing ifolder Server in the DMZ with ifolder Data inside the Firewall Implementing iflder Server in the DMZ with iflder Data inside the Firewall Nvell Cl Slutins AppNte JULY 2004 OBJECTIVES The bjectives f this dcumentatin are as fllws: T cnfigure

More information

Job Profile Data & Reporting Analyst (Grant Fund)

Job Profile Data & Reporting Analyst (Grant Fund) Jb Prfile Data & Reprting Analyst (Grant Fund) Directrate Lcatin Reprts t Hurs Finance Slihull Finance Directr Nminally 37 hurs but peratinally available at all times t meet Cmpany requirements Cntract

More information

Policy on Free and Open-source Software. Government Policy of Iceland

Policy on Free and Open-source Software. Government Policy of Iceland Plicy n Free and Open-surce Sftware Gvernment Plicy f Iceland Prime Minister s Office December 2007 Intrductin Free and pen-surce sftware is sftware based n a surce cde which the authrs chse t make public

More information

Readme File. Purpose. Introduction to Data Integration Management. Oracle s Hyperion Data Integration Management Release 9.2.

Readme File. Purpose. Introduction to Data Integration Management. Oracle s Hyperion Data Integration Management Release 9.2. Oracle s Hyperin Data Integratin Management Release 9.2.1 Readme Readme File This file cntains the fllwing sectins: Purpse... 1 Intrductin t Data Integratin Management... 1 Data Integratin Management Adapters...

More information

Table of Contents. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY.

Table of Contents. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS SUMMARY. Table f Cntents Tp Pricing and Licensing Questins... 2 Why shuld custmers be excited abut Micrsft SQL Server 2012?... 2 What are the mst significant changes t the pricing and licensing fr SQL Server?...

More information

FUJITSU Software ServerView Suite ServerView PrimeCollect

FUJITSU Software ServerView Suite ServerView PrimeCollect User Guide - English FUJITSU Sftware ServerView Suite ServerView PrimeCllect Editin February 2015 Cmments Suggestins Crrectins The User Dcumentatin Department wuld like t knw yur pinin f this manual. Yur

More information


HOW TO SELECT A LIFE INSURANCE COMPANY HOW TO SELECT A LIFE INSURANCE COMPANY There will prbably be hundreds f life insurance cmpanies t chse frm when yu decide t purchase a life insurance plicy. Hw d yu decide which ne? Mst cmpanies are quite

More information

Firewall/Proxy Server Settings to Access Hosted Environment. For Access Control Method (also known as access lists and usually used on routers)

Firewall/Proxy Server Settings to Access Hosted Environment. For Access Control Method (also known as access lists and usually used on routers) Firewall/Prxy Server Settings t Access Hsted Envirnment Client firewall settings in mst cases depend n whether the firewall slutin uses a Stateful Inspectin prcess r ne that is cmmnly referred t as an

More information

Welcome to Remote Access Services (RAS)

Welcome to Remote Access Services (RAS) Welcme t Remte Access Services (RAS) Our gal is t prvide yu with seamless access t the TD netwrk, including the TD intranet site, yur applicatins and files, and ther imprtant wrk resurces -- whether yu

More information

ITIL Service Offerings & Agreement (SOA) Certification Program - 5 Days

ITIL Service Offerings & Agreement (SOA) Certification Program - 5 Days ITIL Service Offerings & Agreement (SOA) Certificatin Prgram - 5 Days Prgram Overview ITIL is a set f best practices guidance that has becme a wrldwide-adpted framewrk fr Infrmatin Technlgy Services Management

More information

COE: Hybrid Course Request for Proposals. The goals of the College of Education Hybrid Course Funding Program are:

COE: Hybrid Course Request for Proposals. The goals of the College of Education Hybrid Course Funding Program are: COE: Hybrid Curse Request fr Prpsals The gals f the Cllege f Educatin Hybrid Curse Funding Prgram are: T supprt the develpment f effective, high-quality instructin that meets the needs and expectatins

More information

PBS TeacherLine Course Syllabus

PBS TeacherLine Course Syllabus 1 Title Fstering Cperative Learning, Discussin, and Critical Thinking in Elementary Math (Grades 1-5) Target Audience This curse is intended fr pre-service and in-service grades 1-5 teachers. Curse Descriptin

More information

Business Intelligence and DataWarehouse workshop

Business Intelligence and DataWarehouse workshop Business Intelligence and DataWarehuse wrkshp Benefits: Enables the Final year BE student/ Junir IT prfessinals t get a perfect blend f thery and practice n Business Intelligence and Data warehuse s as

More information

Department of CSIT Organizes a 2-Day Skill Development Workshop On Basic Networking Tools and Concepts. On 14-15 March 2016

Department of CSIT Organizes a 2-Day Skill Development Workshop On Basic Networking Tools and Concepts. On 14-15 March 2016 Department f CSIT Organizes a 2-Day Skill Develpment Wrkshp On Basic Netwrking Tls and Cncepts On 14-15 March 2016 In Jint Cllabratin With Skill Develpment Cell Guru Ghasidas Vishwavidyalaya, Bilaspur

More information

1 Google Apps for Education Henrico County, Virginia

1 Google Apps for Education Henrico County, Virginia 1 Ggle Apps fr Educatin Henric Cunty, Virginia PROGRAM CATEGORY: Infrmatin Technlgy 1. Abstract f the Prgram Henric Cunty Public Schls (HCPS) prides itself n its innvative apprach t instructin. We believe

More information

State of Wisconsin DET Dedicated Virtual Host Services Offering Definition

State of Wisconsin DET Dedicated Virtual Host Services Offering Definition State f Wiscnsin DET Dedicated Virtual Hst Services Offering Definitin Dcument Revisin Histry Date Versin Creatr Ntes 10/29/2010 1.0 Phil Staley Initial draft 11/3/2010 1.1 Phil Staley Ryan McKee Secnd

More information



More information

Systems Load Testing Appendix

Systems Load Testing Appendix Systems Lad Testing Appendix 1 Overview As usage f the Blackbard Academic Suite grws and its availability requirements increase, many custmers lk t understand the capability f its infrastructure. As part

More information

Custom Portlets. an unbiased review of the greatest Practice CS feature ever. Andrew V. Gamet

Custom Portlets. an unbiased review of the greatest Practice CS feature ever. Andrew V. Gamet Custm Prtlets an unbiased review f the greatest Practice CS feature ever Andrew V. Gamet Descriptin In Practice CS, the firm can use any f the fur dashbards t quickly display relative infrmatin. The Firm,

More information

The complete notes are available at

The complete notes are available at Reprt: April 12, 2011 By Erick Engelke I have rganized my tasks arund tw majr prblems: 1. Define the new active directry a. Dmain Name Service fr the dmain - cmplete b. Dmain layut, structuring f Organizatinal

More information

CORE 8 to 9 Data Migration Guide

CORE 8 to 9 Data Migration Guide CORE 8 t 9 Data Migratin Guide i CORE 8 t 9 Data Migratin Guide Cpyright 2009-2015 Vitech Crpratin. All rights reserved. N part f this dcument may be reprduced in any frm, including, but nt limited t,

More information

Integrating With incontact dbprovider & Screen Pops

Integrating With incontact dbprovider & Screen Pops Integrating With incntact dbprvider & Screen Pps incntact has tw primary pints f integratin. The first pint is between the incntact IVR (script) platfrm and the custmer s crprate database. The secnd pint

More information

Watlington and Chalgrove GP Practice - Patient Satisfaction Survey 2011

Watlington and Chalgrove GP Practice - Patient Satisfaction Survey 2011 Watlingtn and Chalgrve GP - Patient Satisfactin Survey 2011 Backgrund During ne week in Nvember last year patients attending either the Chalgrve r the Watlingtn surgeries were asked t cmplete a survey

More information

Best Practices on Monitoring Hotel Review Sites By Max Starkov and Mariana Mechoso Safer

Best Practices on Monitoring Hotel Review Sites By Max Starkov and Mariana Mechoso Safer January 2008 Best Practices n Mnitring Htel Review Sites By Max Starkv and Mariana Mechs Safer Hteliers ften ask HeBS hw they can mnitr the Internet chatter surrunding their htels and whether r nt they

More information

The actions discussed below in this Appendix assume that the firm has already taken three foundation steps:

The actions discussed below in this Appendix assume that the firm has already taken three foundation steps: MAKING YOUR MARK 6.1 Gd Practice This sectin presents an example f gd practice fr firms executing plans t enter the resurces sectr supply chain fr the first time, r fr thse firms already in the supply

More information

Online Network Administration Degree Programs

Online Network Administration Degree Programs Online Schls, Degrees & Prgrams Blg Abut Archives Cntact Online Netwrk Administratin Degree Prgrams A Netwrk Administratr is smene respnsible fr the maintenance and perfrmance f cmputer hardware and sftware

More information

Ensuring end-to-end protection of video integrity

Ensuring end-to-end protection of video integrity White paper Ensuring end-t-end prtectin f vide integrity Prepared by: Jhn Rasmussen, Senir Technical Prduct Manager, Crprate Business Unit, Milestne Systems Date: May 22, 2015 Milestne Systems Ensuring

More information