Etnaviv Notes for OpenDingux 2013-09-13
This is the first release of OpenDingux for the GCW Zero that includes Etnaviv. The Etnaviv project was first published around the start of the year 2013. It has made very good progress since then and now the time has come when we think it is ready to be included in OpenDingux.
What "ready" means is that there is enough functionality to run several games without game breaking glitches. There are sure to be many bugs and missing features, since this is a young and complex project. But we feel now is the right time to put it into the hands of all developers.
The Graphics Stack
The graphics stack contains the following components: (from high to low level)
- Application, such as a game or emulator
- Mesa: OpenGL ES implementation
- Gallium: user space driver, generic part
- Etnaviv: user space driver, hardware specific part
- Galcore: kernel driver by Vivante
Etnaviv Overview
Features
- APIs: OpenGL ES 1 and OpenGL ES 2
- textures: 2D, cube maps
- texture compression: DXT1-5, ETC
- anti-aliasing: 1x, 2x or 4x MSAA
- vertex texture fetch
- 16 or 24 bit depth buffer
- 0 bit or 8 bit stencil buffer
- 8, 16 or 32 bit (OES_element_index_uint) indices for glDrawElements
GLES 1 extensions
- GL_EXT_blend_minmax
- GL_EXT_multi_draw_arrays
- GL_EXT_texture_filter_anisotropic
- GL_EXT_texture_lod_bias
- GL_OES_byte_coordinates
- GL_OES_fixed_point
- GL_OES_stencil_wrap
- GL_OES_compressed_paletted_texture
- GL_OES_query_matrix
- GL_OES_read_format
- GL_OES_single_precision
- GL_OES_draw_texture
- GL_OES_matrix_get
- GL_OES_point_size_array
- GL_OES_point_sprite
- GL_EXT_texture_format_BGRA8888
- GL_OES_compressed_ETC1_RGB8_texture
- GL_OES_depth24
- GL_OES_element_index_uint
- GL_OES_fbo_render_mipmap
- GL_OES_framebuffer_object
- GL_OES_mapbuffer
- GL_OES_rgb8_rgba8
- GL_OES_stencil8
- GL_OES_texture_env_crossbar
- GL_OES_texture_mirrored_repeat
- GL_OES_texture_npot
- GL_OES_EGL_image
- GL_OES_packed_depth_stencil
- GL_OES_texture_cube_map
- GL_APPLE_texture_max_level
- GL_EXT_discard_framebuffer
- GL_EXT_read_format_bgra
- GL_OES_blend_equation_separate
- GL_OES_blend_func_separate
- GL_OES_blend_subtract
- GL_OES_EGL_image_external
- GL_OES_vertex_array_object
- GL_EXT_map_buffer_range
- GL_OES_surfaceless_context
GLES 2 extensions
- GL_EXT_blend_minmax
- GL_EXT_multi_draw_arrays
- GL_EXT_texture_filter_anisotropic
- GL_EXT_texture_format_BGRA8888
- GL_OES_compressed_ETC1_RGB8_texture
- GL_OES_depth24
- GL_OES_element_index_uint
- GL_OES_fbo_render_mipmap
- GL_OES_mapbuffer
- GL_OES_rgb8_rgba8
- GL_OES_standard_derivatives
- GL_OES_stencil8
- GL_OES_texture_npot
- GL_OES_EGL_image
- GL_OES_depth_texture
- GL_OES_packed_depth_stencil
- GL_EXT_texture_type_2_10_10_10_REV
- GL_OES_get_program_binary
- GL_APPLE_texture_max_level
- GL_EXT_discard_framebuffer
- GL_EXT_read_format_bgra
- GL_NV_fbo_color_attachments
- GL_OES_EGL_image_external
- GL_OES_vertex_array_object
- GL_EXT_unpack_subimage
- GL_NV_draw_buffers
- GL_NV_read_buffer
- GL_EXT_map_buffer_range
- GL_OES_surfaceless_context
Known Bugs and Issues
- loops in shaders are not supported
- indirect access to uniforms not yet supported
- GLSL "discard" not yet supported
- gl_FrontFacing not yet supported
- GLSL "texture" bias parameter not yet supported
- GLSL "textureLod" not yet supported
- reading from framebuffer (when supertiled) not yet supported
- extension "GL_OES_texture_3D" is erroneously reported (but with max texture size 0); the hardware has no support for 3D textures
Development
All required headers and libs are included in the 2013-09-13 release of the OpenDingux toolchain for the GCW Zero; older releases won't work.
Use EGL to set up a context for OpenGL ES. We're looking at adding SDL2 as an alternative, but EGL is the only option in this release. Add -DMESA_EGL_NO_X11_HEADERS to your compile flags, so Mesa's EGL headers won't try to include X11 functionality which OpenDingux doesn't have.
Example code can be found in this project.
Performance Tips
- always use vertex buffer objects (VBOs)
- put vertices into one interleaved VBO, not multiple VBOs
- use compressed textures (DXTx or ETC) where possible
- when drawing with glDrawElements use the smallest possible index size
Debug Tips
The apitrace tool is included in the rootfs. It can capture GL ES calls made by an application for later replay and inspection.
Bug Reports
Although most of the critical problems should have been solved by now, some
unknown rendering bugs and crashes may still be present.
Report issues and rendering problems in the Etnaviv issue tracker.
When reporting an issue provide as much information as possible about the GLES
and GLSL functions and extensions used and other information that may be useful
for narrowing down the problem.
If possible, attach an apitrace dump that shows the problem (run apitrace trace -a egl executable on the device and send the resulting .trace file). These can be replayed on various devices to find out when divergences occur.
Contributing
The latest source code can be found at on github: Etnaviv and
Mesa.
Help with development is very welcome. Join #etnaviv on irc.freenode.net via IRC or web chat) to contact the developers.