Additional resources

Functions in the bbutil API

The Core Native OpenGL ES templates in the Momentics IDE for BlackBerry provide several useful utility functions that you can use to set up your EGL app. These functions are in the bbutil.c file in the project.

bbutil_init_egl(screen_context_t ctx)
This function initializes a native window and EGL for use. The ctx parameter is the libscreen context that is used for the EGL setup and must be created before it is passed to this function. If initialization is successful, EXIT_SUCCESS is returned; otherwise EXIT_FAILURE is returned.
bbutil_terminate()
This function cleans up EGL and the native window, so all of the components that were allocated during initialization are deallocated.
bbutil_swap()
This function swaps the default window surface to the screen using the eglSwapBuffers() function.
bbutil_load_font(const char* font_file, int point_size, int dpi)
This function loads a font file and should be called after a successful return of the bbutil_init_egl() function. The font_file parameter is a string of the absolute path of the font file. The point_size parameter specifies the height and width of the glyphs to be generated. The dpi parameter specifies the horizontal and vertical resolution, which is used with the point_size to generate glyphs. If the font file is loaded successfully, a pointer to a font_t structure is returned; otherwise, NULL is returned.
bbutil_destroy_font(font_t* font)
This function deletes the specified font texture from memory.
bbutil_render_text(font_t* font, const char* msg, float x, float y, float r, float g, float b, float a)
This function renders the specified message using the current font from the specified lower-left coordinates. The font parameter specifies the font to use for rendering. The msg parameter specifies the message to display. The x and y parameters specify the position of the lower-left corner of the text string in the overall coordinate space where you want to render the text. Finally, the r, g, b, and a parameters specify the RGBA color for the text to render with.
bbutil_measure_text(font_t* font, const char* msg, float* width, float* height)
This function returns the nonscaled width and height of a string. The font parameter specifies the font to use for measuring a string size. The msg parameter specifies the message to get the size of. The width and height pointer parameters are filled with calculated width and height, respectively.
bbutil_load_texture(const char* filename, int* width, int* height, float* tex_x, float* tex_y, unsigned int* tex)
This function creates and loads a texture from a .png file and must be called after a successful return of the bbutil_init_egl() function. The filename parameter specifies the path to the texture .png file to load. The pointer parameters, height and width, are returned with the height and width of the created texture. The pointer parameters (tex_x and tex_y) are returned with the changed texture coordinates. Finally, the pointer parameter, tex, is returned with a handle of the created texture.
bbutil_calculate_dpi(screen_context_t ctx)
This function returns the DPI for a given screen. The ctx parameter specifies the screen context that corresponds to the given screen.
bbutil_rotate_screen_surface(int angle)
This function rotates the screen to a given angle. The angle parameter must be set to 0, 90, 180, or 270. If the screen was successfully rotated, EXIT_SUCCESS is returned; otherwise EXIT_FAILURE is returned.

If you're using OpenGL ES 1.1 and OpenGL ES 2.0 in the same app, you need to handle the setup that is provided by the bbutil API yourself.

Porting your OpenGL ES code

In most cases, porting your code to BlackBerry 10 from other platforms that support OpenGL ES APIs (for example, iOS or Android) is a one-to-one mapping.

If you are porting from Android SDK, the OpenGL ES APIs are accessible using Java classes: GLES11 and GLES20. You need to create an instance of each class to access to the necessary methods. The Java methods in the GLES11 and GLES20 classes map closely to the native OpenGL ES APIs. Consider the following example:

Clearing the color buffer using the GLES11 class:

GLES11.glClear(GL_COLOR_BUFFER_BIT);

The code sample above corresponds to:

glClear(GL_COLOR_BUFFER_BIT);

For more information on porting your code to BlackBerry 10, see Gaming & Porting.

Determining capabilities and extensions

The OpenGL ES specifications define the minimum set of requirements for a company that implements the APIs must meet, but an implementation may extend beyond the minimum requirements to provide additional functionality. Each implementation may vary based on the version of the specification that is implemented, the graphics hardware, and OS version the device is running. So, the capabilities between implementations vary. Let's look at how to determine the capabilities.

Determine implementation-dependent values

OpenGL ES has specific values that show its capabilities on a device. You must query the capabilities to make sure that you don't exceed the limits of a particular value, such as the number of blue bitplanes you use in the color buffer. We obtain all of the following constants by querying the appropriate glGet*() function. We determine the appropriate function from the return value that we expect.

The following table shows constants that describe some capabilities of any version of OpenGL ES on your device:

Constant Description
GL_ALPHA_BITS The number of alpha bitplanes in the color buffer
GL_BLUE_BITS The number of blue bitplanes in the color buffer
GL_DEPTH_BITS The number of bitplanes in the depth buffer
GL_GREEN_BITS The number of green bitplanes in the color buffer
GL_MAX_TEXTURE_SIZE The number of texture units that are supported
GL_RED_BITS The number of red bitplanes in the color buffer
GL_STENCIL_BITS The number of bitplanes in the stencil buffer

The following table shows constants that describe some capabilities of OpenGL ES 1.1 on your device:

The constant Description
GL_MAX_CLIP_PLANES The maximum number of application-defined clipping planes
GL_MAX_LIGHTS The maximum number of lights
GL_MAX_MODELVIEW_STACK_DEPTH The maximum supported depth of the modelview matrix stack
GL_MAX_PROJECTION_STACK_DEPTH The maximum supported depth of the projection matrix stack
GL_MAX_TEXTURE_SIZE An estimate of the largest texture that the OpenGL ES implementation can handle
GL_MAX_TEXTURE_STACK_DEPTH The maximum supported depth of the texture matrix stack
GL_MAX_VIEWPORT_DIMS The maximum supported width and height of the viewport

The following table shows constants that describe some capabilities of OpenGL ES 2.0 on your device:

The constant Description
GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS The maximum number of supported texture image units that can be used to access texture maps from the vertex shader and the fragment processor combined
GL_MAX_CUBE_MAP_TEXTURE_SIZE A estimate of the largest cube-map texture that the OpenGL ES implementation can handle
GL_MAX_FRAGMENT_UNIFORM_VECTORS The maximum number of four-element vectors that can be held in uniform variable storage for a fragment shader
GL_MAX_RENDERBUFFER_SIZE The largest render buffer width and height that the OpenGL ES implementation can handle
GL_MAX_TEXTURE_IMAGE_UNITS The maximum supported texture image units that can be used to access texture maps from the fragment shader
GL_MAX_VARYING_VECTORS The maximum number of four-element floating-point vectors that are available for interpolating varying variables
GL_MAX_VERTEX_ATTRIBS The maximum number of four-component generic vertex attributes
GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS The maximum number of supported texture image units that can be used to access texture maps from the vertex shader
GL_MAX_VERTEX_UNIFORM_VECTORS The maximum number of four-element vectors that can be held in uniform variable storage for a vertex shader

For more information, see the OpenGL ES 1.1 manual pages, OpenGL ES 2.0 manual pages, or OpenGL ES 3.0 manual pages.

Get version information

You can use the glGetString() function to obtain information about the vendor, the renderer used, and version information. The function accepts a constant as a parameter and returns a string that describes the current OpenGL ES configuration.

Constant Description
GL_VENDOR The company that is responsible for the implementation
GL_RENDERER The name of the renderer that is used
GL_VERSION A version or release number
GL_SHADING_LANGUAGE_VERSION A version or release number for the shading language
GL_EXTENSIONS A space-separated list of supported extensions

Check for OpenGL ES extensions

You can determine the available OpenGL ES extensions at any time with the following code:

	char *extensions = (char *) glGetString(GL_EXTENSIONS);

Extensions are specific to the OpenGL ES implementation on the hardware platform.

Capabilities by graphics platform

This section describes the capabilities that each graphics platform supports.

PowerVR SGX

The PowerVR SGX series of graphics processors are used for the BlackBerry PlayBook tablet and certain BlackBerry Z10 smartphones. It's designed to support OpenGL ES 2.0, and it implements the OpenGL ES 1.1 API more efficiently using OpenGL ES 2.0 shaders. For more information, see the PowerVR SGX OpenGL ES 2.0 Application Development Recommendations on the Imagination Technologies website.

Tile-based deferred rendering

The PowerVR SGX platform uses tile-based deferred rendering, where rasterization is performed on a per-tile basis instead of the entire frame buffer, as traditional immediate-mode rendering does. This approach enables the hardware to retrieve geometry data only when it renders each tile, which minimizes memory bandwidth requirements. Color, depth, and stencil buffers are rasterized using fast on-chip memory instead of system memory.

Limits on OpenGL ES 1.1

Description Minimum value Maximum value
Number of application-defined clipping planes 6 6
Number of lights 8 8
Supported depth of the modelview matrix stack 16 matrices 16 matrices
Supported depth of the projection matrix stack 2 matrices 2 matrices
Texture size 64 x 64 pixels 2048 x 2048 pixels
Supported depth of the texture matrix stack 2 matrices 4 matrices
Number of supported texture units 1 4

Limits on OpenGL ES 2.0

Description Minimum value Maximum value
Texture image units that can be used to access texture maps from the vertex shader and fragment processor combined 8 8
Size of cube map texture 16 x 16 pixels 2048 x 2048 pixels
Number of uniform vectors 16 64
Render buffer width and height 1 x 1 pixel 2048 x 2048 pixels
Number of texture image units that can be accessed by texture maps from the fragment shader 8 8
Texture size 64 x 64 pixels 2048 x 2048 pixels
Number of varying vectors 8 8
Number of vertex attributes 8 16
Number of texture image units accessed by texture maps from the vertex shader 0 8
Number of uniform vectors that can be held for a vertex shader 128 128

Qualcomm Adreno 225

The Qualcomm Adreno 225 is the graphics processor for the BlackBerry Q10 smartphone and certain BlackBerry Z10 smartphones. It supports OpenGL ES 1.1 and 2.0, and also supports EGL 1.4.

Limits on OpenGL ES 1.1

Description Minimum value Maximum value
Number of application-defined clipping planes 6 6
Number of lights 8 8
Supported depth of the modelview matrix stack 16 matrices 16 matrices
Supported depth of the projection matrix stack 2 matrices 4 matrices
Texture size 64 x 64 pixels 4096 x 4096 pixels
Supported depth of the texture matrix stack 2 matrices 2 matrices
Number of supported texture units 1 2

Limits on OpenGL ES 2.0

Description Minimum value Maximum value
Texture image units that can be used to access texture maps from the vertex shader and fragment processor combined 8 20
Size of cube map texture 16 x 16 pixels 4096 x 4096 pixels
Number of uniform vectors 16 221
Render buffer width and height 1 x 1 pixel 4096 x 4096 pixels
Number of texture image units that can be accessed by texture maps from the fragment shader 8 16
Texture size 64 x 64 pixels 4096 x 4096 pixels
Number of varying vectors 8 8
Number of vertex attributes 8 16
Number of texture image units that can be accessed by texture maps from the vertex shader 0 4
Number of uniform vectors that can be held for a vertex shader 128 251

Qualcomm Adreno 320

The Qualcomm Adreno 320 is the graphics processor for the BlackBerry Z30 smartphone. It supports OpenGL ES 1.1, 2.0, and 3.0, and also supports EGL 1.4.

Limits on OpenGL ES 1.1

Description Minimum value Maximum value
Number of application-defined clipping planes 6 6
Number of lights 8 8
Supported depth of the modelview matrix stack 16 matrices 16 matrices
Supported depth of the projection matrix stack 2 matrices 4 matrices
Texture size 64 x 64 pixels 4096 x 4096 pixels
Supported depth of the texture matrix stack 2 matrices 2 matrices
Number of supported texture units 1 2

Limits on OpenGL ES 2.0

Description Minimum value Maximum value
Texture image units that can be used to access texture maps from the vertex shader and fragment processor combined 8 32
Size of cube map texture 16 x 16 pixels 4096 x 4096 pixels
Number of uniform vectors 16 224
Render buffer width and height 1 x 1 pixel 4096 x 4096 pixels
Number of texture image units that can be accessed by texture maps from the fragment shader 8 16
Texture size 64 x 64 pixels 4096 x 4096 pixels
Number of varying vectors 8 16
Number of vertex attributes 8 16
Number of texture image units that can be accessed by texture maps from the vertex shader 0 16
Number of uniform vectors that can be held for a vertex shader 128 256

Limits on OpenGL ES 3.0

Description Minimum value Maximum value
Texture image units that can be used to access texture maps from the vertex shader and fragment processor combined 8 32
Size of cube map texture 16 x 16 pixels 4096 x 4096 pixels
Number of uniform vectors 16 224
Render buffer width and height 1 x 1 pixel 4096 x 4096 pixels
Number of texture image units that can be accessed by texture maps from the fragment shader 8 16
Texture size 64 x 64 pixels 4096 x 4096 pixels
Number of varying vectors 8 16
Number of vertex attributes 8 16
Number of texture image units that can be accessed by texture maps from the vertex shader 0 16
Number of uniform vectors that can be held for a vertex shader 128 256

BlackBerry 10 Device Simulator

The extensions and capabilities of the BlackBerry 10 Device Simulator differ from hardware platforms because it's a simulated environment. It supports OpenGL ES 1.1 and 2.0.

Limits on OpenGL ES 1.1

Description Minimum value Maximum value
Number of application-defined clipping planes 6 6
Number of lights 8 24
Supported depth of the modelview matrix 16 matrices 32 matrices
Supported depth of the projection matrix 2 matrices 32 matrices
Texture size 64 x 64 pixels 8192 x 8192 pixels
Supported depth of the texture matrix 2 matrices 10 matrices
Number of supported texture units 1 8

Limits on OpenGL ES 2.0

Description Minimum value Maximum value
Texture image units that can be used to access texture maps from the vertex shader and fragment processor combined 8 16
Size of cube map texture 16 x 16 pixels 2048 x 2048 pixels
Number of uniform vectors that can be held for a fragment shader 16 224
Render buffer width and height 1 x 1 pixel 16384 x 16384 pixels
Texture image units that can be accessed by texture maps from the fragment shader 8 16
Texture size 64 x 64 pixels 8192 x 8192 pixels
Number of varying vectors 8 8
Number of vertex attributes 8 16
Texture image units that can be accessed by texture maps from the vertex shader 0 0
Number of uniform vectors that can be held for a vertex shader 128 256

Last modified: 2015-03-31



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus