esUtil.h

   1 //
   2 // Book:      OpenGL(R) ES 2.0 Programming Guide
   3 // Authors:   Aaftab Munshi, Dan Ginsburg, Dave Shreiner
   4 // ISBN-10:   0321502795
   5 // ISBN-13:   9780321502797
   6 // Publisher: Addison-Wesley Professional
   7 // URLs:      http://safari.informit.com/9780321563835
   8 //            http://www.opengles-book.com
   9 //
  10
  11 /*
  12  * (c) 2009 Aaftab Munshi, Dan Ginsburg, Dave Shreiner
  13  *
  14  * Permission is hereby granted, free of charge, to any person obtaining a
  15  * copy of this software and associated documentation files (the "Software"),
  16  * to deal in the Software without restriction, including without limitation
  17  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  18  * and/or sell copies of the Software, and to permit persons to whom the
  19  * Software is furnished to do so, subject to the following conditions:
  20  *
  21  * The above copyright notice and this permission notice shall be included
  22  * in all copies or substantial portions of the Software.
  23  *
  24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  29  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  30  * DEALINGS IN THE SOFTWARE.
  31  */
  32
  33 //
  34 /// \file ESUtil.h
  35 /// \brief A utility library for OpenGL ES.  This library provides a
  36 ///        basic common framework for the example applications in the
  37 ///        OpenGL ES 2.0 Programming Guide.
  38 //
  39 #ifndef ESUTIL_H
  40 #define ESUTIL_H
  41
  42 ///
  43 //  Includes
  44 //
  45 #include <GLES2/gl2.h>
  46 #include <EGL/egl.h>
  47
  48 #ifdef __cplusplus
  49
  50 extern "C" {
  51 #endif
  52
  53
  54 ///
  55 //  Macros
  56 //
  57 #define ESUTIL_API
  58 #define ESCALLBACK
  59
  60
  61 /// esCreateWindow flag - RGB color buffer
  62 #define ES_WINDOW_RGB           0
  63 /// esCreateWindow flag - ALPHA color buffer
  64 #define ES_WINDOW_ALPHA         1
  65 /// esCreateWindow flag - depth buffer
  66 #define ES_WINDOW_DEPTH         2
  67 /// esCreateWindow flag - stencil buffer
  68 #define ES_WINDOW_STENCIL       4
  69 /// esCreateWindow flat - multi-sample buffer
  70 #define ES_WINDOW_MULTISAMPLE   8
  71
  72
  73 ///
  74 // Types
  75 //
  76
  77 #ifndef FALSE
  78 #define FALSE 0
  79 #endif
  80 #ifndef TRUE
  81 #define TRUE 1
  82 #endif
  83
  84 typedef struct
  85 {
  86     GLfloat   m[4][4];
  87 } ESMatrix;
  88
  89 typedef struct _escontext
  90 {
  91    /// Put your user data here...
  92    void*       userData;
  93
  94    /// Window width
  95    GLint       width;
  96
  97    /// Window height
  98    GLint       height;
  99
 100    /// Window handle
 101    EGLNativeWindowType  hWnd;
 102
 103    /// EGL display
 104    EGLDisplay  eglDisplay;
 105
 106    /// EGL context
 107    EGLContext  eglContext;
 108
 109    /// EGL surface
 110    EGLSurface  eglSurface;
 111
 112    /// Callbacks
 113    void (ESCALLBACK *drawFunc) ( struct _escontext * );
 114    void (ESCALLBACK *keyFunc) ( struct _escontext *, unsigned char, int, int );
 115    void (ESCALLBACK *updateFunc) ( struct _escontext *, float deltaTime );
 116 } ESContext;
 117
 118
 119 ///
 120 //  Public Functions
 121 //
 122
 123 //
 124 ///
 125 /// \brief Initialize ES framework context.  This must be called before calling any other functions.
 126 /// \param esContext Application context
 127 //
 128 void ESUTIL_API esInitContext ( ESContext *esContext );
 129
 130 //
 131 /// \brief Create a window with the specified parameters
 132 /// \param esContext Application context
 133 /// \param title Name for title bar of window
 134 /// \param width Width in pixels of window to create
 135 /// \param height Height in pixels of window to create
 136 /// \param flags Bitfield for the window creation flags
 137 ///         ES_WINDOW_RGB     - specifies that the color buffer should have R,G,B channels
 138 ///         ES_WINDOW_ALPHA   - specifies that the color buffer should have alpha
 139 ///         ES_WINDOW_DEPTH   - specifies that a depth buffer should be created
 140 ///         ES_WINDOW_STENCIL - specifies that a stencil buffer should be created
 141 ///         ES_WINDOW_MULTISAMPLE - specifies that a multi-sample buffer should be created
 142 /// \return GL_TRUE if window creation is succesful, GL_FALSE otherwise
 143 GLboolean ESUTIL_API esCreateWindow ( ESContext *esContext, const char *title, GLint width, GLint height, GLuint flags );
 144
 145 //
 146 /// \brief Start the main loop for the OpenGL ES application
 147 /// \param esContext Application context
 148 //
 149 void ESUTIL_API esMainLoop ( ESContext *esContext );
 150
 151 //
 152 /// \brief Register a draw callback function to be used to render each frame
 153 /// \param esContext Application context
 154 /// \param drawFunc Draw callback function that will be used to render the scene
 155 //
 156 void ESUTIL_API esRegisterDrawFunc ( ESContext *esContext, void (ESCALLBACK *drawFunc) ( ESContext* ) );
 157
 158 //
 159 /// \brief Register an update callback function to be used to update on each time step
 160 /// \param esContext Application context
 161 /// \param updateFunc Update callback function that will be used to render the scene
 162 //
 163 void ESUTIL_API esRegisterUpdateFunc ( ESContext *esContext, void (ESCALLBACK *updateFunc) ( ESContext*, float ) );
 164
 165 //
 166 /// \brief Register an keyboard input processing callback function
 167 /// \param esContext Application context
 168 /// \param keyFunc Key callback function for application processing of keyboard input
 169 //
 170 void ESUTIL_API esRegisterKeyFunc ( ESContext *esContext,
 171                                     void (ESCALLBACK *drawFunc) ( ESContext*, unsigned char, int, int ) );
 172 //
 173 /// \brief Log a message to the debug output for the platform
 174 /// \param formatStr Format string for error log.
 175 //
 176 void ESUTIL_API esLogMessage ( const char *formatStr, ... );
 177
 178 //
 179 ///
 180 /// \brief Load a shader, check for compile errors, print error messages to output log
 181 /// \param type Type of shader (GL_VERTEX_SHADER or GL_FRAGMENT_SHADER)
 182 /// \param shaderSrc Shader source string
 183 /// \return A new shader object on success, 0 on failure
 184 //
 185 GLuint ESUTIL_API esLoadShader ( GLenum type, const char *shaderSrc );
 186
 187 //
 188 ///
 189 /// \brief Load a vertex and fragment shader, create a program object, link program.
 190 ///        Errors output to log.
 191 /// \param vertShaderSrc Vertex shader source code
 192 /// \param fragShaderSrc Fragment shader source code
 193 /// \return A new program object linked with the vertex/fragment shader pair, 0 on failure
 194 //
 195 GLuint ESUTIL_API esLoadProgram ( const char *vertShaderSrc, const char *fragShaderSrc );
 196
 197
 198 //
 199 /// \brief Generates geometry for a sphere.  Allocates memory for the vertex data and stores
 200 ///        the results in the arrays.  Generate index list for a TRIANGLE_STRIP
 201 /// \param numSlices The number of slices in the sphere
 202 /// \param vertices If not NULL, will contain array of float3 positions
 203 /// \param normals If not NULL, will contain array of float3 normals
 204 /// \param texCoords If not NULL, will contain array of float2 texCoords
 205 /// \param indices If not NULL, will contain the array of indices for the triangle strip
 206 /// \return The number of indices required for rendering the buffers (the number of indices stored in the indices array
 207 ///         if it is not NULL ) as a GL_TRIANGLE_STRIP
 208 //
 209 int ESUTIL_API esGenSphere ( int numSlices, float radius, GLfloat **vertices, GLfloat **normals,
 210                              GLfloat **texCoords, GLuint **indices );
 211
 212 //
 213 /// \brief Generates geometry for a cube.  Allocates memory for the vertex data and stores
 214 ///        the results in the arrays.  Generate index list for a TRIANGLES
 215 /// \param scale The size of the cube, use 1.0 for a unit cube.
 216 /// \param vertices If not NULL, will contain array of float3 positions
 217 /// \param normals If not NULL, will contain array of float3 normals
 218 /// \param texCoords If not NULL, will contain array of float2 texCoords
 219 /// \param indices If not NULL, will contain the array of indices for the triangle strip
 220 /// \return The number of indices required for rendering the buffers (the number of indices stored in the indices array
 221 ///         if it is not NULL ) as a GL_TRIANGLES
 222 //
 223 int ESUTIL_API esGenCube ( float scale, GLfloat **vertices, GLfloat **normals,
 224                            GLfloat **texCoords, GLuint **indices );
 225
 226 //
 227 /// \brief Loads a 24-bit TGA image from a file
 228 /// \param fileName Name of the file on disk
 229 /// \param width Width of loaded image in pixels
 230 /// \param height Height of loaded image in pixels
 231 ///  \return Pointer to loaded image.  NULL on failure.
 232 //
 233 char* ESUTIL_API esLoadTGA ( char *fileName, int *width, int *height );
 234
 235
 236 //
 237 /// \brief multiply matrix specified by result with a scaling matrix and return new matrix in result
 238 /// \param result Specifies the input matrix.  Scaled matrix is returned in result.
 239 /// \param sx, sy, sz Scale factors along the x, y and z axes respectively
 240 //
 241 void ESUTIL_API esScale(ESMatrix *result, GLfloat sx, GLfloat sy, GLfloat sz);
 242
 243 //
 244 /// \brief multiply matrix specified by result with a translation matrix and return new matrix in result
 245 /// \param result Specifies the input matrix.  Translated matrix is returned in result.
 246 /// \param tx, ty, tz Scale factors along the x, y and z axes respectively
 247 //
 248 void ESUTIL_API esTranslate(ESMatrix *result, GLfloat tx, GLfloat ty, GLfloat tz);
 249
 250 //
 251 /// \brief multiply matrix specified by result with a rotation matrix and return new matrix in result
 252 /// \param result Specifies the input matrix.  Rotated matrix is returned in result.
 253 /// \param angle Specifies the angle of rotation, in degrees.
 254 /// \param x, y, z Specify the x, y and z coordinates of a vector, respectively
 255 //
 256 void ESUTIL_API esRotate(ESMatrix *result, GLfloat angle, GLfloat x, GLfloat y, GLfloat z);
 257
 258 //
 259 // \brief multiply matrix specified by result with a perspective matrix and return new matrix in result
 260 /// \param result Specifies the input matrix.  new matrix is returned in result.
 261 /// \param left, right Coordinates for the left and right vertical clipping planes
 262 /// \param bottom, top Coordinates for the bottom and top horizontal clipping planes
 263 /// \param nearZ, farZ Distances to the near and far depth clipping planes.  Both distances must be positive.
 264 //
 265 void ESUTIL_API esFrustum(ESMatrix *result, float left, float right, float bottom, float top, float nearZ, float farZ);
 266
 267 //
 268 /// \brief multiply matrix specified by result with a perspective matrix and return new matrix in result
 269 /// \param result Specifies the input matrix.  new matrix is returned in result.
 270 /// \param fovy Field of view y angle in degrees
 271 /// \param aspect Aspect ratio of screen
 272 /// \param nearZ Near plane distance
 273 /// \param farZ Far plane distance
 274 //
 275 void ESUTIL_API esPerspective(ESMatrix *result, float fovy, float aspect, float nearZ, float farZ);
 276
 277 //
 278 /// \brief multiply matrix specified by result with a perspective matrix and return new matrix in result
 279 /// \param result Specifies the input matrix.  new matrix is returned in result.
 280 /// \param left, right Coordinates for the left and right vertical clipping planes
 281 /// \param bottom, top Coordinates for the bottom and top horizontal clipping planes
 282 /// \param nearZ, farZ Distances to the near and far depth clipping planes.  These values are negative if plane is behind the viewer
 283 //
 284 void ESUTIL_API esOrtho(ESMatrix *result, float left, float right, float bottom, float top, float nearZ, float farZ);
 285
 286 //
 287 /// \brief perform the following operation - result matrix = srcA matrix * srcB matrix
 288 /// \param result Returns multiplied matrix
 289 /// \param srcA, srcB Input matrices to be multiplied
 290 //
 291 void ESUTIL_API esMatrixMultiply(ESMatrix *result, ESMatrix *srcA, ESMatrix *srcB);
 292
 293 //
 294 //// \brief return an indentity matrix
 295 //// \param result returns identity matrix
 296 //
 297 void ESUTIL_API esMatrixLoadIdentity(ESMatrix *result);
 298
 299 #ifdef __cplusplus
 300 }
 301 #endif
 302
 303 #endif // ESUTIL_H