OpenGL ES API control features.
Defines that can be used to control the self-certification / GL API wrapping behaviour. These definitions MUST be done to all code using OpenGL ES. Mixed use case (disabled for some code and enabled for some) is not supported!
QGAMEOPENGLES_LOG_TO_FILE
- On Symbian^3 writes the log output to the
- On Maemo, Meego, Desktop Linux, and MAC writes the log file to
- On Windows, log file goes to
NOTE: this DISABLES qDebug() based tracing (default) that should show up on Qt Creator window (application output) if your device/qt creator is configured corretly.
[TODO: verify that logging is fully disabled if wrapper is used without flags OR with just the shadowing flag]
QGAMEOPENGLES_LOG_TO_FILE_IS_UNBUFFERED
- Define this WITH QGAMEOPENGLES_LOG_TO_FILE to make writes are unbuffered
- Buffered version is better for faster execution, unbuffered is better for giving as much of trace as possible in cases where application is crashing for example
QGAMEOPENGLES_OPENGLES_SHADOWING
- enables texture & VBO shadowing, where shadow copies of textures and VBO's are kept and server side copies are deleted on focus loss and re-created on focus gain
- RAM usage is increased by the amount of texture and VBO memory used by the game
- This can be used on platforms that require special GPU memory handling at focus loss / gained (enable ONLY for Symbian^3 devices for now)
- Since some GL API calls are wrapped and copies of such things as shader program objects vertex attribute array bindings, texture objects, VBOS, etc. are kept, there is some slight performance penalty due to this. Developer can always opt to not use this feature, but must then handle the focus loss / gained processing themselves.
- Some texture update operations (glCopyTex[Sub]Image2D) are very slow on some architectures as the only way to read the updates to texture is via glReadPixels()
- FBO based texture updates are NOT shadowed to keep per-frame render-to-texture working at somewhat decent speeds. These need to be handled by the developer
- WARNING: this ONLY works with 2D textures right now! (3D / Cube textures are not touched)
QGAMEOPENGLES_TRACK_GRAM_USAGE
- tracks an estimate of graphics memory usage by calculating memory taken by texture uploads etc.
- also on platforms that support direct graphics memory usage queries, gives values from those APIs too
- fairly low performance impact
- warns about not meeting focus lost criterias (e.g., on Symbian^3, GRAM usage should be squeezed to as low as 50kB to be absolutely sure to avoid getting killed)
QGAMEOPENGLES_DRAW_CALL_DEBUGGING
- checks for VBO out of bounds accesses (ASSERTS on these)
- checks if draw calls draw degenerate triangles in triangle lists (unnecessary)
- big RAM (need to keep copies of VBO index buffers) and modest CPU performance impact
QGAMEOPENGLES_GL_ERROR_WARNINGS
- runs glGetError() after each GL call and prints out to log if error codes exist
- also warns about failed shader compiles and program links and prints out GL shader error messages
- warns about other misc issues too (e.g., driver issues found on buggy drivers etc.)
QGAMEOPENGLES_GL_ERROR_ASSERTS
- runs glGetError() after each GL call and asserts if GL is in error state
- also asserts about failed shader compiles and program links and prints out shader error messages
QGAMEOPENGLES_FULL_DEBUG
- combines all debugging flags
QGAMEOPENGLES_FULL_GL_CALL_LOG
- Dumps all GL calls to a log (IDE output or FILE depending on if QGAMEOPENGLES2_LOG_TO_FILE is enabled or not)
- This is useful for providing GL call traces to a 3rd party to figure out why the performance is slow or why program/os/driver is crashing
- SLOWS down the execution somewhat
- Combine with UNBUFFERED log write if you are giving a trace log leading to a crash to catch as many calls to the trace as possible
QGAMEOPENGLES_CALCULATE_STATS (NOT IMPLEMENTED YET!!!!)
- prints average FPS over 200 frames
- low performance impact
in future:
- tracks per average stats (draw calls per frame)
FUTURE ADDITIONS (NOT IMPLEMETED YET):
QGAMEOPENGLES_PERFORMANCE_WARNINGS (NOT IMPLEMENTED YET!!!!)
- warns about certain code sequences that are bad for performance
- modest performance impact
QGAMEOPENGLES_SHADER_VALIDATOR
- validates shader compiles against lowest common denominators in OpenGL ES 2.0 and GLSL ES specs
- checks for using more attributes in vertex shaders than is bare minimum maximum of GL ES spec
- checks for using more uniform storage that is mandated as a bare minimum maximum in GL ES spec
- fairly big performance impact
- warn about certain perf problems wrt. mediump vs. highp and discardWrapping mode passed to the wrapper. Developerss should not use this directly (subject to changes).
- Enumerator:
-
| EOPENGLES_PASSTHROUGH |
|
| EOPENGLES_SHADOWING |
Keep shadow copies of textures & VBOs in RAM to help in focus lost/gained situations.
|
| EOPENGLES_TRACK_GRAM_USAGE |
Track graphics memory usage.
|
| EOPENGLES_CALCULATE_STATS |
Keep simple frame stats (draw calls / frame etc.).
|
| EOPENGLES_DRAW_CALL_DEBUGGING |
Warn about out of bound accesses of VBOs etc.
|
| EOPENGLES_PERFORMANCE_WARNINGS |
Calculate frame statistics and warn about poor GL behaviour.
|
| EOPENGLES_GL_ERROR_WARNINGS |
Run glGetError() after each GL call, print.
|
| EOPENGLES_GL_ERROR_ASSERTS |
Run glGetError() after each GL call, assert.
|
| EOPENGLES_SHADER_VALIDATOR |
Run shader validator at each shader compile.
|
| EOPENGLES_LOG_TO_FILE |
Log to file instead (buffered).
|
| EOPENGLES_LOG_TO_FILE_IS_UNBUFFERED |
Log to file instead (unbuffered).
|
| EOPENGLES_FULL_GL_CALL_LOG |
Log all GL calls.
|
| EOPENGLES_FULL_DEBUG |
Enable all debug features (default).
|
