Press on the image to return to the main documentation page.
OpenGL
Written by Andrew Graham
Android includes support for high performance 3D graphics via the OpenGL ES API. OpenGL ES is a flavor of the OpenGL specification intended for embedded devices. Versions of OpenGL ES are loosely peered to versions of the primary OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds to OpenGL 1.3. If the application you have in mind is possible with OpenGL 1.3 on a desktop system, it should be possible on Android.
Android does include some basic support for OpenGL ES 1.1, the support is not complete, and should not be relied upon at this time.
Support for the Android OpenGL Interfaces GL10, GL10Ext, GL11, GL11Ext and GL11ExtensionPack is implemented in this library.
The specific API provided by Android is similar to the J2ME JSR239 OpenGL ES API. However, it may not be identical, so watch out for deviations.
This library also contains a Matrix object that operates on 4x4 OpenGL matrices and a Visibility object that imlpements a collection of utility methods for computing the visibility of triangle meshes.
This object does all the drawing work and is an exposure one or more of the Android OpenGL interfaces.
The GL1 function and parameter names mirror those of the GL10, GL10Ext, GL11, GL11Ext and GL11ExtensionPack interfaces. These interfaces should be present on all Android versions from 1.6 but just in case not the ability to check the presence of each is provided.
Some variations of functions that use native buffers instead of arrays are omitted, generally where there is an array equivalent. Where there is not an equivalent using a float array has been synthesised and the name suffixed with an "f".
Note that although documented in the Android documentation, and included in this library for completeness, it seems that most, if not all, of the GL11ExtensionPack glget... functions throw an UnsupportedOperationException. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Define a viewing transformation in terms of an eye point, a center of view, and an up vector. eyeX eye point X eyeY eye point Y eyeZ eye point Z centerX center of view X centerY center of view Y centerZ center of view Z upX up vector X upY up vector Y upZ up vector Z
Set up a perspective projection matrix. fovy specifies the field of view angle, in degrees, in the Y direction. aspect specifies the aspect ratio that determines the field of view in the x direction. Aspect ratio is the ratio of x (width) to y (height). zNear specifies the distance from the viewer to the near clipping plane (always positive). zFar specifies the distance from the viewer to the far clipping plane (always positive).
An implementation of SurfaceView that uses the dedicated surface for displaying OpenGL rendering. A GLSurfaceView provides the following features:
Manages a surface, which is a special piece of memory that can be composited into the Android view system. Manages an EGL display, which enables OpenGL to render into a surface. Renders on a dedicated thread to decouple rendering performance from the UI thread. Supports both on-demand and continuous rendering.
At present a reasonable set of drawing defaults are used to set up the GLSurfaceView. More control may be available in a future release of this library glFrustrumf must be called in the SurfaceChanged event to define a frustrum otherwise the GLSurfaceView is ready to be drawn on.
Presently there is an unwanted field "ba" visible to Basic4android. Ignore this field. This field appears due to a feature (bug?) in the Basic4android documentation doclet.
This view raises the following three events all of which run on a separate rendering thread and NOT on the main thread of the application. Because of this cosw running in these events must no attempt to manipulate GUI elements. The RunOnGuiThread method can be used to invoke a Sub to tun on the main thread and QueueEvent used to invoke a Sub to run on the rendering thread.
SurfaceCreated Called when the surface is created or recreated. Called when the rendering thread starts and whenever the EGL context is lost. The EGL context will typically be lost when the Android device awakes after going to sleep. Since this method is called at the beginning of rendering, as well as every time the EGL context is lost, this method is a convenient place to put code to create resources that need to be created when the rendering starts, and that need to be recreated when the EGL context is lost. Textures are an example of a resource that you might want to create here. Note that when the EGL context is lost, all OpenGL resources associated with that context will be automatically deleted. You do not need to call the corresponding "glDelete" methods such as glDeleteTextures to manually delete these lost resources.
SurfaceChanged Called when the surface has changed size. Called after the surface is created and whenever the OpenGL ES surface size changes. Typically you will set your viewport here. If your camera is fixed then you could also set your projection matrix here
Draw Called to draw the current frame. This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
Events:
Click LongClick Draw(gl As GL1) 'The view wants to be drawn using the supplied GL10 SurfaceChanged(gl As GL1, width As Int, height As Int) 'Called when the surface has changed size. SurfaceCreated(gl As GL1) 'Called when the surface is created or recreated.
Check glError() after every GL call and throw an exception if glError indicates that an error has occurred. This can be used to help track down which OpenGL ES call is causing an error.
DEBUG_LOG_GL_CALLSAsInt
Log GL calls to the system log at "verbose" level with tag "GLSurfaceView".
DebugFlagsAsInt
Get or set the debug flags to a new value. The value is constructed by OR-together zero or more of the DEBUG_CHECK_* constants. The debug flags take effect whenever a surface is created. The default value is zero.
EnabledAsBoolean
HeightAsInt
Initialize (RenderModeAsInt, EventNameAsString)
Initializes the GLSurfaceView in the specified render mode installing a config chooser which will choose a config as close to 16-bit RGB as possible, with a depth buffer as close to 16-bits as possible. Calls SetEGLConfigChooser(true);
Initializes the GLSurfaceView in the specified render mode installing a config chooser which will choose a config with 8bit RGBA with the specified depth size and stencil size.
Inform the view that the activity is paused. The owner of this view must call this method when the activity is paused. Calling this method will pause the rendering thread. Must not be called before a renderer has been set.
QueuedEventExceptionAsException
If an uncaught exception occurs when running a queued event it is saved here because an uncaught exception on a non-main thread will close the application.
Queue a Sub to be run on the GL rendering thread. This can be used to communicate with the Renderer on the rendering thread and safely run non-atomic functions without any further thread synchronisation. Using this method to update data used while rendering ensures that the data will only be changed when rendering is not occurring,. If an uncaught exception occurs when running the event it is saved in the QueuedEventException property.
RemoveView
RenderModeAsInt
Gets or sets the rendering mode. When renderMode is RENDERMODE_CONTINUOUSLY, the renderer is called repeatedly to re-render the scene. When renderMode is RENDERMODE_WHEN_DIRTY, the scene is only rendered when the surface is created, or when requestRender() is called. Defaults to RENDERMODE_CONTINUOUSLY.
Using RENDERMODE_WHEN_DIRTY can improve battery life and overall system performance by allowing the GPU and CPU to idle when the view does not need to be updated.
This method can only be called after setRenderer(Renderer)
RENDERMODE_CONTINUOUSLYAsInt
The renderer is called continuously to re-render the scene.
RENDERMODE_WHEN_DIRTYAsInt
The renderer only renders when the surface is created, or when requestRender() is called.
RequestFocusAsBoolean
RequestRender
Request that the renderer render a frame. This method is typically used when the render mode has been set to RENDERMODE_WHEN_DIRTY, so that frames are only rendered on demand. May be called from any thread. Must not be called before a renderer has been set.
Resume
Inform the view that the activity is resumed. The owner of this view must call this method when the activity is resumed. Calling this method will recreate the OpenGL display and resume the rendering thread. Must not be called before a renderer has been set.
Causes the specified Sub to be scheduled for execution on the main GUI thread. This mechanism is the only way a thread can access GUI items. This call returns immediately. If it is necessary for the thread to wait for the result of the GUI operation then it should wait on a Lock that will be reset by the called Sub after it haas completed the GUI operation. Sometimes it seems that if the user presses the back button, and maybe in other scenarions, then Android loses the message and the GUI thread doesn't get it and the Sub isn't run and the Lock isn't freed so it may be advisable in this case to use WaitFor with a reasonably long timeout and retry until it returns True.
Returns True if the Sub was found otherwise returns False.
Parameters mInv the array that holds the output inverted matrix mInvOffset an offset into mInv where the inverted matrix is stored. m the input array mOffset an offset into m where the matrix is stored.
Returns true if the matrix could be inverted, false if it could not.
Multiply two 4x4 matrices together and store the result in a third 4x4 matrix. In matrix notation: result = lhs x rhs. Due to the way matrix multiplication works, the result matrix will have the same effect as first multiplying by the rhs matrix, then multiplying by the lhs matrix. This is the opposite of what you might expect. The same float array may be passed for result, lhs, and/or rhs. However, the result element values are undefined if the result elements overlap either the lhs or rhs elements.
Parameters result The float array that holds the result. resultOffset The offset into the result array where the result is stored. lhs The float array that holds the left-hand-side matrix. lhsOffset The offset into the lhs array where the lhs is stored. rhs The float array that holds the right-hand-side matrix. rhsOffset The offset into the rhs array where the rhs is stored.
Multiply a 4 element vector by a 4x4 matrix and store the result in a 4 element column vector. In matrix notation: result = lhs x rhs The same float array may be passed for resultVec, lhsMat, and/or rhsVec. However, the resultVec element values are undefined if the resultVec elements overlap either the lhsMat or rhsVec elements.
Parameters resultVec The float array that holds the result vector. resultVecOffset The offset into the result array where the result vector is stored. lhsMat The float array that holds the left-hand-side matrix. lhsMatOffset The offset into the lhs array where the lhs is stored. rhsVec The float array that holds the right-hand-side vector. rhsVecOffset The offset into the rhs vector where the rhs vector is stored.
Parameters m source matrix. mOffset index into m where the matrix starts. a angle to rotate in degrees. x scale factor x. y scale factor y. z scale factor z.
Rotates matrix m in place by angle a (in degrees) around the axis (x, y, z).
Parameters rm returns the result. rmOffset index into rm where the result matrix starts. m source matrix. mOffset index into m where the source matrix starts. a angle to rotate in degrees. x scale factor x. y scale factor y. z scale factor z.
Rotates matrix m by angle a (in degrees) around the axis (x, y, z) to another matrix.
Parameters rm returns the result. rmOffset index into rm where the result matrix starts. m source matrix. mOffset index into m where the source matrix starts. a angle to rotate in degrees. x scale factor x. y scale factor y. z scale factor z.
Scales matrix m by x, y, and z, putting the result in sm.
Parameters sm returns the result. smOffset index into sm where the result matrix starts. m source matrix. mOffset index into m where the source matrix starts. x scale factor x. y scale factor y. z scale factor z.
SetIdentityM (sm() AsFloat, smOffsetAsInt)
Sets matrix m to the identity matrix.
Parameters m returns the result. mOffset index into m where the result matrix starts.
Converts Euler angles x, y, z to a rotation matrix.
Parameters rm returns the result. rmOffset index into rm where the result matrix starts. x angle of rotation, in degrees. y angle of rotation, in degrees. z angle of rotation, in degrees.
Rotates matrix m by angle a (in degrees) around the axis (x, y, z). Parameters rm returns the result. rmOffset index into rm where the result matrix starts. x scale factor x. y scale factor y. z scale factor z.
Translates matrix m by x, y, and z, putting the result in tm.
Parameters tm returns the result. tmOffset index into sm where the result matrix starts. m source matrix. mOffset index into m where the source matrix starts. x translation factor x. y translation factor y. z translation factor z.
Parameters mTrans the array that holds the output inverted matrix. mTransOffset an offset into mInv where the inverted matrix is stored. m the input array. mOffset an offset into m where the matrix is stored.
Compute a bounding sphere for a set of points. It is approximately the minimal bounding sphere of an axis-aligned box that bounds the points.
Parameters positions positions in x, y, z triples positionsOffset offset into positions array positionsCount number of position triples to process sphere array containing the output as (x, y, z, r) sphereOffset offset where the sphere data will be written
Given an OpenGL ES ModelView-Projection matrix (which implicitly describes a frustum) and a list of spheres, determine which spheres intersect the frustum.
A ModelView-Projection matrix can be computed by multiplying a Projection matrix by a ModelView matrix (in that order.). There are several possible ways to obtain the current ModelView and Projection matrices. The most generally applicable way is to keep track of the current matrices in application code. If that is not convenient, there are two optional OpenGL ES extensions which may be used to read the current matrices from OpenGL ES:
GL10 - Ext.glQueryMatrixxOES GL11 - GL_MODELVIEW_MATRIX_FLOAT_AS_INT_BITS_OES and GL11 - GL_PROJECTION_MATRIX_FLOAT_AS_INT_BITS_OES
The problem with reading back the matrices is that your application will only work with devices that support the extension(s) that it uses.
A frustum is a six-sided truncated pyramid that defines the portion of world space that is visible in the view.
Spheres are described as four floating point values: x, y, z, and r, in world-space coordinates. R is the radius of the sphere.
Parameters mvp a float array containing the mode-view-projection matrix mvpOffset The offset of the mvp data within the mvp array. spheres a float array containing the sphere data. spheresOffset an offset into the sphere array where the sphere data starts spheresCount the number of spheres to cull. results an integer array containing the indices of the spheres that are either contained entirely within or intersect the frustum. resultsOffset an offset into the results array where the results start. resultsCapacity the number of array elements available for storing results.
Returns the number of spheres that intersected the frustum. Can be larger than resultsCapacity, in which case only the first resultsCapacity results are written into the results array.
Test whether a given triangle mesh is visible on the screen. The mesh is specified as an indexed triangle list.
Parameters ws the world space to screen space transform matrix, as an OpenGL column matrix. wsOffset an index into the ws array where the data starts. positions the vertex positions (x, y, z). positionsOffset the index in the positions array where the data starts. indices the indices of the triangle list. The indices are expressed as chars because they are unsigned 16-bit values. indicesOffset the index in the indices array where the index data starts. indexCount the number of indices in use. Typically a multiple of three. If not a multiple of three, the remaining one or two indices will be ignored.
Returns 2 if all of the mesh is visible, 1 if some part of the mesh is visible, 0 if no part is visible.
Top