Difference between revisions of "Porting to GLES from GL"

From Pandora Wiki
Jump to: navigation, search
(typos)
 
(36 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== Forwords ==
+
== Foreword ==
 
This guide is based on my limited knowledge (I do have barely the requierement) on the subject. I'm open to get edits on it, in fact it is encouraged :)
 
This guide is based on my limited knowledge (I do have barely the requierement) on the subject. I'm open to get edits on it, in fact it is encouraged :)
 
--[[User:Sebt3|Sebt3]] 17:05, 24 February 2011 (MET)
 
--[[User:Sebt3|Sebt3]] 17:05, 24 February 2011 (MET)
== Requierement ==
+
 
 +
You might want to try [http://boards.openpandora.org/index.php/topic/11506-opengl-implementation-tldr-more-games/page-1 libGL] before following the instructions on this page.
 +
 
 +
== Requirements ==
 
* a working toolchain
 
* a working toolchain
 
* average C/C++ knowledge
 
* average C/C++ knowledge
* basic knowledge on how GL or GLES works
+
* basic knowledge of how GL or GLES works
 
* read [[OpenGL_ES_1.1_Tutorial]]
 
* read [[OpenGL_ES_1.1_Tutorial]]
  
You might also want to have a look at others work in that matter :
+
You might also want to have a look at others' work in this matter :
 
* http://pickle.gp2x.de/source/kenlabes-src.zip
 
* http://pickle.gp2x.de/source/kenlabes-src.zip
 
* http://pickle.gp2x.de/gish_src.zip  
 
* http://pickle.gp2x.de/gish_src.zip  
Line 17: Line 20:
  
 
For more references, have a look to :  
 
For more references, have a look to :  
* [http://www.khronos.org/opengles/documentation/opengles1_0/html/ opengles references]
+
* [http://www.khronos.org/opengles/sdk/1.1/docs/man/ opengles references] or [http://www.khronos.org/opengles/sdk/docs/man/ opengles references 2]
 
* [http://www.opengl.org/sdk/docs/man/ opengl references]
 
* [http://www.opengl.org/sdk/docs/man/ opengl references]
  
 
== Before starting ==
 
== Before starting ==
Choose a simple GL game for your first experience. Working with a large and complexe codebase is not what you want to do at first.
+
Choose a simple GL game for your first experience. Working with a large and complex codebase is not what you want to do at first.
  
To have a good view of what you'll need to do, here a simple (and incomplete) bash script that will list you all the code lines you'll need to work with :
+
To have a good view of what you'll need to do, here is a simple (and incomplete) bash script that will list you all the code lines you'll need to work with :
 
<source lang=bash>
 
<source lang=bash>
 
#!/bin/sh
 
#!/bin/sh
 
+
 
search() {
 
search() {
find . -name "*.h" -o -name "*.c" -o -name "*.cpp" -exec grep -Hn "$*" {} \;
+
find . \( -name "*.h" -o -name "*.c" -o -name "*.cpp" -o -name "*.cxx" \) -exec grep -Hn "$*" {} \;
 
}
 
}
 
+
 
listIssues() {
 
listIssues() {
 
search SDL_WM_GrabInput
 
search SDL_WM_GrabInput
Line 48: Line 51:
 
search glTexImage2D
 
search glTexImage2D
 
search glBegin
 
search glBegin
 +
search glX
 +
search glRect
 +
search glNewList
 
}
 
}
 +
 +
listIssues|sort -u
  
listIssues|sort -u
 
 
</source>
 
</source>
Run that from the source directory. The less lines displayed the better.
+
Run that from the source directory. The fewer lines displayed, the better.
  
If your project use some GL libraries, get that to build first. Here are some libraries ported to gles :
+
If your project uses some GL libraries, get that to build first. Here are some libraries ported to GLES :
 
* GLU : http://code.google.com/p/glues/ (you might want to grab a binary version with headers in zaz or briquolo pnd)
 
* GLU : http://code.google.com/p/glues/ (you might want to grab a binary version with headers in zaz or briquolo pnd)
* FTGL : http://code.google.com/p/ftgles/ (I do have fixed version [http://sebt3.openpandora.org/src/ftgles-pandora.tar.gz here], if you prefer a binary version, get that in the zaz PND)
+
* FTGL : http://code.google.com/p/ftgles/ (I do have a fixed version [http://sebt3.openpandora.org/src/ftgles-pandora.tar.gz here]; if you prefer a binary version, get that in the zaz PND)
  
 
== Getting it to build ==
 
== Getting it to build ==
You first goal is to have it built. You'll probably need to hack the build system.  
+
Your first goal is to have it built. You'll probably need to hack the build system.  
 
* If it's just Makefiles, replace -lGL with -lGLES_CM -lEGL -lX11.  
 
* If it's just Makefiles, replace -lGL with -lGLES_CM -lEGL -lX11.  
* If it's an autotools project, have a look at how it's done in briquolo for references. (take a look at configure.ac, and follow the enable_gles bits ;) Dont forget the Makefile.am too. Once your edit are in, autoreconf is your friend.)
+
* If it's an autotools project, have a look at how it's done in briquolo for references. (take a look at configure.ac, and follow the enable_gles bits ;) Dont forget the Makefile.am too. Once your edits are in, autoreconf is your friend.)
  
Make sure your build system (or your toolchain) will also set defines some marker to know if it need to build GL or GLES code. Having one too for pandora specific hack might show itself usefull too. I'm using "-DPANDORA -DHAVE_GLES" myself.
+
Make sure your build system (or your toolchain) will also set defines some marker to know if it needs to build GL or GLES code. Having one too for pandora specific hack might show itself useful too. I'm using "-DPANDORA -DHAVE_GLES" myself.
  
Now try to build it. You'll have error in the build process. to fix them, for now, just #ifdef out the offending lines. Here is what to do with the include instructions :
+
Now try to build it. You'll have errors in the build process. To fix them, for now, just #ifdef out the offending lines. Here is what to do with the include instructions :
 
<source lang=c>
 
<source lang=c>
 
#if !defined(HAVE_GLES)
 
#if !defined(HAVE_GLES)
Line 82: Line 89:
 
At the end of this process you'll end up with a broken pandora binary. Let's now fix it :D
 
At the end of this process you'll end up with a broken pandora binary. Let's now fix it :D
 
== Adding the EGL context ==
 
== Adding the EGL context ==
Grab the eglport package pickle have built [http://pickle.gp2x.de/source/eglport.zip here]. You will need to add call to it's 4 functions in the sources (make also sure that eglport.c is built and linked in the build process). Here is how your sources should look at the end :
+
Grab the eglport package Pickle has built [http://sourceforge.net/p/eglport/code-0/ here]. You will need to add a call to its 3 functions in the sources (make sure, also, that eglport.c is built and linked in the build process). Here is how your sources should look at the end :
 
<source lang=c>
 
<source lang=c>
 +
#if !defined(HAVE_GLES)
 
#include <GL/gl.h>
 
#include <GL/gl.h>
 
#else
 
#else
Line 89: Line 97:
 
#include "eglport.h"
 
#include "eglport.h"
 
#endif
 
#endif
 +
 +
#include <SDL/SDL.h>
  
 
int main( void )
 
int main( void )
Line 95: Line 105:
  
 
         SDL_Init( SDL_INIT_VIDEO );
 
         SDL_Init( SDL_INIT_VIDEO );
#if !defined(HAVE_GLES)
 
      if (!EGL_Open())
 
exit(1);
 
#endif
 
  
 
// some more initialisations
 
// some more initialisations
 +
        SDL_Surface* screen;
  
 
#if !defined(HAVE_GLES)
 
#if !defined(HAVE_GLES)
Line 106: Line 113:
 
#else
 
#else
 
         screen = SDL_SetVideoMode( 800, 480, 0, SDL_SWSURFACE | SDL_FULLSCREEN );
 
         screen = SDL_SetVideoMode( 800, 480, 0, SDL_SWSURFACE | SDL_FULLSCREEN );
EGL_Init();
+
      if (EGL_Open( 800, 480 ))
 +
exit(1);
 
#endif
 
#endif
  
Line 124: Line 132:
  
 
#if defined(HAVE_GLES)
 
#if defined(HAVE_GLES)
EGL_Destroy();
+
EGL_Close();
 
#endif
 
#endif
 
         SDL_Quit();
 
         SDL_Quit();
Line 133: Line 141:
  
 
Please note that :
 
Please note that :
* EGL_Init have to called just after the SDL initialisation of the VIDEO layer
+
* SDL_SetVideoMode arguments have to be those given here (aka good resolution, and no SDL_OPENGL flag)
* SDL_SetVideoMode arguments have to be those fiven here (aka good resolution, and no SDL_OPENGL flag)
+
* EGL_Open goes just after SDL_SetVideoMode, the parameters are the same resolution used in SDL_SetVideoMode
* EGL_Init goes just after SDL_SetVideoMode
+
* '''All''' SDL_GL_SwapBuffers calls have to be converted to EGL_SwapBuffers calls.
* '''All''' SDL_GL_SwapBuffers call have to be converted to EGL_SwapBuffers calls.
+
* EGL_Close is called before quitting SDL (or closing the video if that's separated in your original source).
* You have to call EGL_Destroy before quitting SDL (or closing the video if that's splitted in your original source).
+
When built, your source should run on the Pandora cleanly (ok, you'll have a black screen, but that's expected as we haven't converted the drawing yet).
When built, your source should run on the pandora cleanly (ok you'll have a black screen, but that's expected as we havent converted the drawing yet.
+
 
 +
''In addition to these instructions, I had to add "#include <X11/Xlib.h>" and change all the comments from line to block in eglport.c --lunixbochs
 +
* ''That was in old version (of eglport), you shouldn't need it it new version  --M-HT
  
 
== Converting the easy stuff ==
 
== Converting the easy stuff ==
This part could have been done while getting the game built, but I prefered splitting the 2 process for readability. Fell free to work as you please :D. Remember that all you have #ifdef out in the building part have to be converted, dont forget anything.
+
This part could have been done while getting the game built, but I preferred splitting the 2 processes for readability. Feel free to work as you please :D. Remember that all you have #ifdef out in the building part has to be converted; don't forget anything.
  
GLES only support float, double (aka GLdouble) dont work. So :
+
GLES only supports float; double (aka GLdouble) doesn't work. So :
 
* any GLdouble should be converted to GLfloat
 
* any GLdouble should be converted to GLfloat
* all GL function call ending with a "d" should have the d remplaced with f.
+
* all GL function calls ending with a "d" should have the d replaced with f.
  
Here are others know conversions :
+
Here are other know conversions :
* GL_CLAMP -> GL_CLAMP_TO_EDGE
+
#define GLdouble    GLfloat
* GL_ONE_MINUS_SRC_ALPHA -> GL_ONE
+
#define GL_CLAMP     GL_CLAMP_TO_EDGE
* glClearDepth -> glClearDepthf
+
#define glClearDepth glClearDepthf
* glOrtho -> glOrthof
+
#define glOrtho     glOrthof
 +
#define glFrustum    glFrustumf
  
 
=== Colors ===
 
=== Colors ===
GLES only know glColor4f as unction to create a color, all the glColor3f, glColor3d and glColor4d have to be converted to glColor4f. If you only have 3 arguments, the last have to be 1.0f (as no transparency).
+
GLES only knows glColor4f as the function to create a color; all the glColor3f, glColor3d, glColor4d or any other color conventions have to be converted to glColor4f. If you only have 3 arguments, the last have to be 1.0f (as no transparency).
 +
 
 +
#define glColor4fv(a) glColor4f(a[0], a[1], a[2], a[3])
 +
#define glColor3fv(a) glColor4f(a[0], a[1], a[2], 1.0f)
 +
#define glColor3f(a,b,c) glColor4f(a, b, c, 1.0f)
  
 
== Converting the immediate mode ==
 
== Converting the immediate mode ==
If you have read [[OpenGL_ES_1.1_Tutorial]], you already have a good idea of what need to be changed here. Here are a few others exemples to help you in your process :
+
If you have read [[OpenGL_ES_1.1_Tutorial]], you already have a good idea of what needs to be changed here. Here are a few other examples to help you in your process :
  
 
1) a simple quad with no texture or color :
 
1) a simple quad with no texture or color :
Line 223: Line 238:
 
#endif
 
#endif
 
</source>
 
</source>
3) a colored quad (note that, as GL is a state machine, the color is only showed once in the GL code, while it is copied for every points on gles) :
+
3) a colored quad (note that, as GL is a state machine, the color is only showed once in the GL code, while it is copied for every point in gles) :
 
<source lang=c>
 
<source lang=c>
 
#if !defined(HAVE_GLES)
 
#if !defined(HAVE_GLES)
Line 259: Line 274:
 
#endif
 
#endif
 
</source>
 
</source>
 +
4) GL_QUAD_STRIP :
 +
<source lang=c>
 +
#if !defined(HAVE_GLES)
 +
        glBegin(GL_QUAD_STRIP);
 +
                // Front
 +
                glVertex3f(-left, 0, front); // bottom left
 +
                glVertex3f(-left-wider, height, front+wider); // top left
 +
                glVertex3f( right, 0, front); // bottom right
 +
                glVertex3f( right+wider, height, front+wider); // top right
 +
 +
                // Right
 +
                glVertex3f( right, 0,-back); // bottom r
 +
                glVertex3f( right+wider, height,-back-wider); // top r
 +
 +
                // Back
 +
                glVertex3f(-left, 0, -back); // bottom right
 +
                glVertex3f(-left-wider, height, -back-wider); // top right
 +
 +
                // Left
 +
                glVertex3f(-left, 0, front); // bottom r
 +
                glVertex3f(-left-wider, height, front+wider); // top r
 +
        glEnd();
 +
#else
 +
        {
 +
        GLfloat vtx1[] = {-left, 0, front,      -left-wider, height, front+wider,      right, 0, front,        right+wider, height, front+wider};
 +
        GLfloat vtx2[] = {right, 0, front,      right+wider, height, front+wider,      right, 0,-back,        right+wider, height,-back-wider};
 +
        GLfloat vtx3[] = {right, 0,-back,      right+wider, height,-back-wider,        -left, 0, -back,        -left-wider, height, -back-wider};
 +
        GLfloat vtx4[] = {-left, 0, -back,      -left-wider, height, -back-wider,      -left, 0, front,        -left-wider, height, front+wider};
 +
        glEnableClientState(GL_VERTEX_ARRAY);
 +
        glVertexPointer(3, GL_FLOAT, 0, vtx1);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
        glVertexPointer(3, GL_FLOAT, 0, vtx2);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
        glVertexPointer(3, GL_FLOAT, 0, vtx3);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
        glVertexPointer(3, GL_FLOAT, 0, vtx4);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
        glDisableClientState(GL_VERTEX_ARRAY);
 +
        }
 +
#endif
 +
</source>
 +
5) using int/short :
 +
<source lang=c>
 +
#if !defined(HAVE_GLES)
 +
    glBegin(GL_QUADS);
 +
        glTexCoord2i(0, 1); glVertex2i(-256, -256);
 +
        glTexCoord2i(0, 0); glVertex2i(-256, 256);
 +
        glTexCoord2i(1, 0); glVertex2i(256, 256);
 +
        glTexCoord2i(1, 1); glVertex2i(256, -256);
 +
    glEnd();
 +
#else
 +
        GLshort vtx1[] = {      -256, -256,    -256, 256,      256, 256,      256, -256      };
 +
        GLshort tex1[] = {      0, 1,          0, 0,          1, 0,          1, 1            };
 +
        glEnableClientState(GL_VERTEX_ARRAY);
 +
        glEnableClientState(GL_TEXTURE_COORD_ARRAY);
  
Here is a list of conversion between GL to GLES draw modes :
+
        glVertexPointer(2, GL_SHORT, 0, vtx1);
 +
        glTexCoordPointer(2, GL_SHORT, 0, tex1);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
 
 +
        glDisableClientState(GL_VERTEX_ARRAY);
 +
        glDisableClientState(GL_TEXTURE_COORD_ARRAY);
 +
#endif
 +
</source>
 +
5) glRect :
 +
<source lang=c>
 +
#ifndef HAVE_GLES
 +
      glRecti ( dx + min[0], dy + min[1],
 +
                dx + max[0], dy + max[1] ) ;
 +
#else
 +
        GLshort vtx1[] = { dx + min[0], dy + min[1],    dx + min[0], dy + max[1],      dx + max[0], dy + max[1],      dx + max[0],    dy + min[1]};
 +
        glEnableClientState(GL_VERTEX_ARRAY);
 +
        glVertexPointer(2, GL_SHORT, 0, vtx1);
 +
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
 +
        glDisableClientState(GL_VERTEX_ARRAY);
 +
#endif
 +
</source>
 +
 
 +
 
 +
 
 +
Note that the last argument of glDrawArrays is the number of points. In these examples, that's always 4 because these all have 4 points. You might want to change that if your object has more (or less) than these 4 points.
 +
 
 +
Here is a list of conversions between GL to GLES draw modes :
 
* GL_POINTS -> GL_POINTS
 
* GL_POINTS -> GL_POINTS
 
* GL_TRIANGLES -> GL_TRIANGLES (or GL_LINE_LOOP if glPolygonMode is set to GL_LINE)
 
* GL_TRIANGLES -> GL_TRIANGLES (or GL_LINE_LOOP if glPolygonMode is set to GL_LINE)
Line 269: Line 365:
  
 
== Textures ==
 
== Textures ==
All textures have to be loaded with with dimentions in power of 2. See [https://github.com/Cpasjuste/GLES2D/blob/master/src/GLES2D_texture.c GLES2D sources] and GLES2D_p2 function for a easy method of doing to work around that. Briquolo had a more advanced method to do so thanks to Paeryn (it also actually scale the texture to that given size).
+
All textures have to be loaded with dimensions in powers of 2. See [https://github.com/Cpasjuste/GLES2D/blob/master/src/GLES2D_texture.c GLES2D sources] and GLES2D_p2 function for an easy method of working around that. Briquolo had a more advanced method of doing so thanks to Paeryn (it also actually scaled the texture to that given size).
  
GLES only support GL_RGB and GL_RGBA as color mode, so your glTexImage2D have to use that ('''arguments 3 and 7''').
+
When loading textures with glTexImage2D, the only supported formats are GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA.
 +
Arguments for internal format and format(3 and 7) must be the same.
 +
Note: one common situation is where the original program uses 3 or 4 (which is valid for opengl) for internal format and GL_RGB or GL_RGBA for format. GLES requires the 3 to be GL_RGB or 4 to be GL_RGBA.
 +
GLES Example:
 +
glTexImage2D( target, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
 +
 
 +
== Display Lists ==
 +
GL Functions: glGenLists, glCallList, glCallLists, glDeleteLists, glNewList
 +
 
 +
This is a feature provided by GL to allow the application to assign a group of GL commands to a display list. This list is remembered by the graphics card and the application only has to call the list once to get the gpu to rerun all of the assigned commands.
 +
GLES does not support this feature and must rerun the set of commands any time the list would have been called.
 +
[http://www.opengl.org/documentation/specs/version1.1/glspec1.1/node123.html Info on Display Lists]
  
 
== Known issues ==
 
== Known issues ==
* glPushAttrib, glPopAttrib and their clients version dont exist. You'll have to manage these state yourself. An other good way is to have all disabled at all time and only enable what needed at the right time.
+
* glPushAttrib, glPopAttrib and their client versions don't exist. You'll have to manage these states yourself. Another good way is to have all disabled at all times and only enable what is needed at the right time. and see racer sources (http://sebt3.openpandora.org/src/?f=racer-pandora-src.tar.bz2) to get a partial implementation
 +
* SDL_WM_GrabInput and SDL_WarpMouse might cause soft freeze of your game. If it does, #ifndef PANDORA them :)
 +
 
 +
[[Category:Development]]
 +
[[Category:Tutorials]]
 +
[[Category:OpenGL ES]]
 +
[[Category:Ports]]

Latest revision as of 10:53, 28 July 2013

Foreword

This guide is based on my limited knowledge (I do have barely the requierement) on the subject. I'm open to get edits on it, in fact it is encouraged :) --Sebt3 17:05, 24 February 2011 (MET)

You might want to try libGL before following the instructions on this page.

Requirements

  • a working toolchain
  • average C/C++ knowledge
  • basic knowledge of how GL or GLES works
  • read OpenGL_ES_1.1_Tutorial

You might also want to have a look at others' work in this matter :

For more references, have a look to :

Before starting

Choose a simple GL game for your first experience. Working with a large and complex codebase is not what you want to do at first.

To have a good view of what you'll need to do, here is a simple (and incomplete) bash script that will list you all the code lines you'll need to work with :

#!/bin/sh
 
search() {
find . \( -name "*.h" -o -name "*.c" -o -name "*.cpp" -o -name "*.cxx" \) -exec grep -Hn "$*" {} \;
}
 
listIssues() {
search SDL_WM_GrabInput
search SDL_WarpMouse
search SDL_GL
search GL_CLAMP
search glColor|grep -v glColor4f
search glPushAttrib
search glPolygonMode
search GL_QUADS |grep glDrawArrays
search SDL_Init
search SDL_OPENGL
search SDL_ShowCursor
search glClearDepth
search SDL_Quit
search gluBuild2DMipmaps
search glTexImage2D
search glBegin
search glX
search glRect
search glNewList
}
 
listIssues|sort -u

Run that from the source directory. The fewer lines displayed, the better.

If your project uses some GL libraries, get that to build first. Here are some libraries ported to GLES :

Getting it to build

Your first goal is to have it built. You'll probably need to hack the build system.

  • If it's just Makefiles, replace -lGL with -lGLES_CM -lEGL -lX11.
  • If it's an autotools project, have a look at how it's done in briquolo for references. (take a look at configure.ac, and follow the enable_gles bits ;) Dont forget the Makefile.am too. Once your edits are in, autoreconf is your friend.)

Make sure your build system (or your toolchain) will also set defines some marker to know if it needs to build GL or GLES code. Having one too for pandora specific hack might show itself useful too. I'm using "-DPANDORA -DHAVE_GLES" myself.

Now try to build it. You'll have errors in the build process. To fix them, for now, just #ifdef out the offending lines. Here is what to do with the include instructions :

#if !defined(HAVE_GLES)
#include <GL/gl.h>
#else
#include <GLES/gl.h>
#endif

Other offending code, should be #ifdef out like this :

#if !defined(HAVE_GLES)
        glClearDepth(1.0f);
#endif

At the end of this process you'll end up with a broken pandora binary. Let's now fix it :D

Adding the EGL context

Grab the eglport package Pickle has built here. You will need to add a call to its 3 functions in the sources (make sure, also, that eglport.c is built and linked in the build process). Here is how your sources should look at the end :

#if !defined(HAVE_GLES)
#include <GL/gl.h>
#else
#include <GLES/gl.h>
#include "eglport.h"
#endif

#include <SDL/SDL.h>

int main( void )
{
	// other stuff here

        SDL_Init( SDL_INIT_VIDEO );

	// some more initialisations
        SDL_Surface* screen;

#if !defined(HAVE_GLES)
        screen = SDL_SetVideoMode( 800, 600, 0, SDL_HWSURFACE | SDL_OPENGL | SDL_FULLSCREEN);
#else
        screen = SDL_SetVideoMode( 800, 480, 0, SDL_SWSURFACE | SDL_FULLSCREEN );
       	if (EGL_Open( 800, 480 ))
		exit(1);
#endif

        // the event loop
        while( quit == 0 ) {
                // management of the even and the game


#if !defined(HAVE_GLES)
        	SDL_GL_SwapBuffers();
#else
		EGL_SwapBuffers();
#endif
        }

	// probably some more clean-ups here

#if defined(HAVE_GLES)
	EGL_Close();
#endif
        SDL_Quit();

        return 0;
}

Please note that :

  • SDL_SetVideoMode arguments have to be those given here (aka good resolution, and no SDL_OPENGL flag)
  • EGL_Open goes just after SDL_SetVideoMode, the parameters are the same resolution used in SDL_SetVideoMode
  • All SDL_GL_SwapBuffers calls have to be converted to EGL_SwapBuffers calls.
  • EGL_Close is called before quitting SDL (or closing the video if that's separated in your original source).

When built, your source should run on the Pandora cleanly (ok, you'll have a black screen, but that's expected as we haven't converted the drawing yet).

In addition to these instructions, I had to add "#include <X11/Xlib.h>" and change all the comments from line to block in eglport.c --lunixbochs

  • That was in old version (of eglport), you shouldn't need it it new version --M-HT

Converting the easy stuff

This part could have been done while getting the game built, but I preferred splitting the 2 processes for readability. Feel free to work as you please :D. Remember that all you have #ifdef out in the building part has to be converted; don't forget anything.

GLES only supports float; double (aka GLdouble) doesn't work. So :

  • any GLdouble should be converted to GLfloat
  • all GL function calls ending with a "d" should have the d replaced with f.

Here are other know conversions :

#define GLdouble     GLfloat
#define GL_CLAMP     GL_CLAMP_TO_EDGE
#define glClearDepth glClearDepthf
#define glOrtho      glOrthof
#define glFrustum    glFrustumf

Colors

GLES only knows glColor4f as the function to create a color; all the glColor3f, glColor3d, glColor4d or any other color conventions have to be converted to glColor4f. If you only have 3 arguments, the last have to be 1.0f (as no transparency).

#define glColor4fv(a) glColor4f(a[0], a[1], a[2], a[3])
#define glColor3fv(a) glColor4f(a[0], a[1], a[2], 1.0f)
#define glColor3f(a,b,c) glColor4f(a, b, c, 1.0f)

Converting the immediate mode

If you have read OpenGL_ES_1.1_Tutorial, you already have a good idea of what needs to be changed here. Here are a few other examples to help you in your process :

1) a simple quad with no texture or color :

#if !defined(HAVE_GLES)
  glBegin(GL_QUADS);
  glVertex2f(-10,-10);
  glVertex2f(10,-10);
  glVertex2f(10,10);
  glVertex2f(-10,10);
  glEnd();
#else
    GLfloat q3[] = {
        -10,-10,
        10,-10,
        10,10,
        -10,10
    };

    glEnableClientState(GL_VERTEX_ARRAY);
    glVertexPointer(2, GL_FLOAT, 0, q3);
    glDrawArrays(GL_TRIANGLE_FAN,0,4);
    glDisableClientState(GL_VERTEX_ARRAY);
#endif

2) a textured quad :

      glBindTexture(GL_TEXTURE_2D, carac->TextureName);
#if !defined(HAVE_GLES)
      glBegin(GL_QUADS);

      glTexCoord2f(0,0);
      glVertex3f(pos[0]-tailleX/2, pos[1]-tailleY/2, 0);
      glTexCoord2f(1,0);
      glVertex3f(pos[0]+tailleX/2, pos[1]-tailleY/2, 0);
      glTexCoord2f(1,1);
      glVertex3f(pos[0]+tailleX/2, pos[1]+tailleY/2, 0);
      glTexCoord2f(0,1);
      glVertex3f(pos[0]-tailleX/2, pos[1]+tailleY/2, 0);

      glEnd();
#else
      GLfloat vtx1[] = {
        pos[0]-tailleX/2, pos[1]-tailleY/2, 0,
        pos[0]+tailleX/2, pos[1]-tailleY/2, 0,
        pos[0]+tailleX/2, pos[1]+tailleY/2, 0,
        pos[0]-tailleX/2, pos[1]+tailleY/2, 0
      };
      GLfloat tex1[] = {
        0,0,
        1,0,
        1,1,
        0,1
      };

      glEnableClientState(GL_VERTEX_ARRAY);
      glEnableClientState(GL_TEXTURE_COORD_ARRAY);

      glVertexPointer(3, GL_FLOAT, 0, vtx1);
      glTexCoordPointer(2, GL_FLOAT, 0, tex1);
      glDrawArrays(GL_TRIANGLE_FAN,0,4);

      glDisableClientState(GL_VERTEX_ARRAY);
      glDisableClientState(GL_TEXTURE_COORD_ARRAY);
#endif

3) a colored quad (note that, as GL is a state machine, the color is only showed once in the GL code, while it is copied for every point in gles) :

#if !defined(HAVE_GLES)
    glBegin(GL_QUADS);
    glColor3d( .1, .1, .7);
    glVertex3d(0, 0, 0);
    glVertex3d(0, -pbarheight, 0);
    glColor3d( 0, 0, 0.5);
    glVertex3d((startupProgress / startupProgressSteps) * pbarwidth, -pbarheight, 0);
    glVertex3d((startupProgress / startupProgressSteps) * pbarwidth, 0, 0);
    glEnd();
#else
    GLfloat vtx1[] = {
        0, 0, 0,
        0, -pbarheight, 0,
        (startupProgress / startupProgressSteps) * pbarwidth, -pbarheight, 0,
        (startupProgress / startupProgressSteps) * pbarwidth, 0, 0
    };
    GLfloat col1[] = {
        .1, .1, .7, 1.0f,
        .1, .1, .7, 1.0f,
        0, 0, 0.5, 1.0f,
        0, 0, 0.5, 1.0f
    };

    glEnableClientState(GL_VERTEX_ARRAY);
    glEnableClientState(GL_COLOR_ARRAY);

    glVertexPointer(3, GL_FLOAT, 0, vtx1);
    glColorPointer(4, GL_FLOAT, 0, col1);
    glDrawArrays(GL_TRIANGLE_FAN,0,4);

    glDisableClientState(GL_COLOR_ARRAY);
    glDisableClientState(GL_VERTEX_ARRAY);
#endif

4) GL_QUAD_STRIP :

#if !defined(HAVE_GLES)
        glBegin(GL_QUAD_STRIP);
                // Front
                glVertex3f(-left, 0, front); // bottom left
                glVertex3f(-left-wider, height, front+wider); // top left
                glVertex3f( right, 0, front); // bottom right
                glVertex3f( right+wider, height, front+wider); // top right

                // Right
                glVertex3f( right, 0,-back); // bottom r
                glVertex3f( right+wider, height,-back-wider); // top r

                // Back
                glVertex3f(-left, 0, -back); // bottom right
                glVertex3f(-left-wider, height, -back-wider); // top right

                // Left
                glVertex3f(-left, 0, front); // bottom r
                glVertex3f(-left-wider, height, front+wider); // top r
        glEnd();
#else
        {
        GLfloat vtx1[] = {-left, 0, front,      -left-wider, height, front+wider,       right, 0, front,        right+wider, height, front+wider};
        GLfloat vtx2[] = {right, 0, front,      right+wider, height, front+wider,       right, 0,-back,         right+wider, height,-back-wider};
        GLfloat vtx3[] = {right, 0,-back,       right+wider, height,-back-wider,        -left, 0, -back,        -left-wider, height, -back-wider};
        GLfloat vtx4[] = {-left, 0, -back,      -left-wider, height, -back-wider,       -left, 0, front,        -left-wider, height, front+wider};
        glEnableClientState(GL_VERTEX_ARRAY);
        glVertexPointer(3, GL_FLOAT, 0, vtx1);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
        glVertexPointer(3, GL_FLOAT, 0, vtx2);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
        glVertexPointer(3, GL_FLOAT, 0, vtx3);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
        glVertexPointer(3, GL_FLOAT, 0, vtx4);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
        glDisableClientState(GL_VERTEX_ARRAY);
        }
#endif

5) using int/short :

#if !defined(HAVE_GLES)
    glBegin(GL_QUADS);
        glTexCoord2i(0, 1); glVertex2i(-256, -256);
        glTexCoord2i(0, 0); glVertex2i(-256, 256);
        glTexCoord2i(1, 0); glVertex2i(256, 256);
        glTexCoord2i(1, 1); glVertex2i(256, -256);
    glEnd();
#else
        GLshort vtx1[] = {      -256, -256,     -256, 256,      256, 256,       256, -256       };
        GLshort tex1[] = {      0, 1,           0, 0,           1, 0,           1, 1            };
        glEnableClientState(GL_VERTEX_ARRAY);
        glEnableClientState(GL_TEXTURE_COORD_ARRAY);

        glVertexPointer(2, GL_SHORT, 0, vtx1);
        glTexCoordPointer(2, GL_SHORT, 0, tex1);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);

        glDisableClientState(GL_VERTEX_ARRAY);
        glDisableClientState(GL_TEXTURE_COORD_ARRAY);
#endif

5) glRect :

#ifndef HAVE_GLES
      glRecti ( dx + min[0], dy + min[1],
                dx + max[0], dy + max[1] ) ;
#else
        GLshort vtx1[] = { dx + min[0], dy + min[1],    dx + min[0], dy + max[1],       dx + max[0], dy + max[1],       dx + max[0],    dy + min[1]};
        glEnableClientState(GL_VERTEX_ARRAY);
        glVertexPointer(2, GL_SHORT, 0, vtx1);
        glDrawArrays(GL_TRIANGLE_FAN,0,4);
        glDisableClientState(GL_VERTEX_ARRAY);
#endif


Note that the last argument of glDrawArrays is the number of points. In these examples, that's always 4 because these all have 4 points. You might want to change that if your object has more (or less) than these 4 points.

Here is a list of conversions between GL to GLES draw modes :

  • GL_POINTS -> GL_POINTS
  • GL_TRIANGLES -> GL_TRIANGLES (or GL_LINE_LOOP if glPolygonMode is set to GL_LINE)
  • GL_QUADS -> GL_TRIANGLE_FAN
  • GL_LINE_STRIP -> GL_LINE_STRIP
  • GL_LINE -> GL_LINE
  • GL_POLYGON -> GL_TRIANGLE_FAN

Textures

All textures have to be loaded with dimensions in powers of 2. See GLES2D sources and GLES2D_p2 function for an easy method of working around that. Briquolo had a more advanced method of doing so thanks to Paeryn (it also actually scaled the texture to that given size).

When loading textures with glTexImage2D, the only supported formats are GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA. Arguments for internal format and format(3 and 7) must be the same. Note: one common situation is where the original program uses 3 or 4 (which is valid for opengl) for internal format and GL_RGB or GL_RGBA for format. GLES requires the 3 to be GL_RGB or 4 to be GL_RGBA. GLES Example:

glTexImage2D( target, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);

Display Lists

GL Functions: glGenLists, glCallList, glCallLists, glDeleteLists, glNewList

This is a feature provided by GL to allow the application to assign a group of GL commands to a display list. This list is remembered by the graphics card and the application only has to call the list once to get the gpu to rerun all of the assigned commands. GLES does not support this feature and must rerun the set of commands any time the list would have been called. Info on Display Lists

Known issues

  • glPushAttrib, glPopAttrib and their client versions don't exist. You'll have to manage these states yourself. Another good way is to have all disabled at all times and only enable what is needed at the right time. and see racer sources (http://sebt3.openpandora.org/src/?f=racer-pandora-src.tar.bz2) to get a partial implementation
  • SDL_WM_GrabInput and SDL_WarpMouse might cause soft freeze of your game. If it does, #ifndef PANDORA them :)