/*
* Copyright 1990-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License version
* 2 only, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License version 2 for more details (a copy is
* included at /legal/license.txt).
*
* You should have received a copy of the GNU General Public License
* version 2 along with this work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 or visit www.sun.com if you need additional
* information or have any questions.
*/
package javax.microedition.khronos.egl;
/**
* The EGL11 interface contains the Java(TM) programming language
* bindings for EGL 1.1. It extends the EGL10 interface.
*
* <p> The documentation in this interface is normative with respect
* to instance variable names and values, method names and signatures,
* and exception behavior. The remaining documentation is placed here
* for convenience and does not replace the normative documentation
* found in the EGL specification and relevant
* extension specifications. EGL documentation is available at the <a
* href="http://www.khronos.org/opengles/spec">Khronos</a> web site.
*/
public interface EGL11 extends EGL10 {
/** EGL 1.1 constant. */
public static final int EGL_CONTEXT_LOST = 0x300E;
/** EGL 1.1 constant. */
public static final int EGL_BIND_TO_TEXTURE_RGB = 0x3039;
/** EGL 1.1 constant. */
public static final int EGL_BIND_TO_TEXTURE_RGBA = 0x303A;
/** EGL 1.1 constant. */
public static final int EGL_MIN_SWAP_INTERVAL = 0x303B;
/** EGL 1.1 constant. */
public static final int EGL_MAX_SWAP_INTERVAL = 0x303C;
/** EGL 1.1 constant. */
public static final int EGL_NO_TEXTURE = 0x305C;
/** EGL 1.1 constant. */
public static final int EGL_TEXTURE_RGB = 0x305D;
/** EGL 1.1 constant. */
public static final int EGL_TEXTURE_RGBA = 0x305E;
/** EGL 1.1 constant. */
public static final int EGL_TEXTURE_2D = 0x305F;
// Surface attributes
/** EGL 1.1 constant. */
public static final int EGL_TEXTURE_FORMAT = 0x3080;
/** EGL 1.1 constant. */
public static final int EGL_TEXTURE_TARGET = 0x3081;
/** EGL 1.1 constant. */
public static final int EGL_MIPMAP_TEXTURE = 0x3082;
/** EGL 1.1 constant. */
public static final int EGL_MIPMAP_LEVEL = 0x3083;
// BindTexImage / ReleaseTexImage buffer target
/** EGL 1.1 constant. */
public static final int EGL_BACK_BUFFER = 0x3084;
/**
* (EGL 1.1 only) Set an EGL surface attribute.
*
* <p><code>eglSurfaceAttrib</code> sets the value of
* <code>attribute</code> for <code>surface</code> to
* <code>value</code>. <code>attribute</code> can be one of the
* following:
*
* <ul>
*
* <li><code>EGL_MIPMAP_LEVEL</code></li>
*
* <p>For mipmap textures, the <code>EGL_MIPMAP_LEVEL</code>
* attribute indicates which level of the mipmap should be
* rendered. If the value of this attribute is outside the range of
* supported mipmap levels, the closest valid mipmap level is
* selected for rendering. The default value is 0.
*
* </ul>
*
* <h4>Notes</h4>
*
* <p>If the value of pbuffer attribute
* <code>EGL_TEXTURE_FORMAT</code> is <code>EGL_NO_TEXTURE</code>,
* if the value of attribute <code>EGL_TEXTURE_TYPE</code> is
* <code>EGL_NO_TEXTURE</code>, or if surface is not a pbuffer, then
* attribute <code>EGL_MIPMAP_LEVEL</code> may be set, but has no
* effect.
*
* <h4>Errors</h4>
*
* <p><code>false</code> is returned on failure, <code>true</code>
* otherwise.
*
* <p><code>EGL_BAD_DISPLAY</code> is generated if
* <code>display</code> is not an EGL display connection.
*
* <p><code>EGL_NOT_INITIALIZED</code> is generated if
* <code>display</code> has not been initialized.
*
* <p><code>EGL_BAD_SURFACE</code> is generated if
* <code>surface</code> is not an EGL surface.
*
* <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
* <code>attribute</code> is not a valid surface attribute.
*
* @param display Specifies the EGL display connection.
* @param surface Specifies the EGL surface.
* @param attribute Specifies the EGL surface attribute to set.
* @param value Specifies the attributes required value.
*
* @exception IllegalArgumentException if <code>display</code> is
* <code>null</code>.
* @exception IllegalArgumentException if <code>surface</code> is
* <code>null</code>.
*
* @return <code>true</code> if the operation succeeds.
*/
boolean eglSurfaceAttrib(EGLDisplay display,
EGLSurface surface,
int attribute,
int value);
/**
* (EGL 1.1 only) Defines a two-dimensional texture image.
*
* <p>The texture image consists of the image data in
* <code>buffer</code> for the specified <code>surface</code>, and
* need not be copied.
*
* <p>The texture target, the texture format and the size of the
* texture components are derived from attributes of the specified
* surface, which must be a pbuffer supporting one of the
* <code>EGL_BIND_TO_TEXTURE_RGB</code> or
* <code>EGL_BIND_TO_TEXTURE_RGBA</code> attributes.
*
* <p>The pbuffer attribute <code>EGL_TEXTURE_FORMAT</code>
* determines the base internal format of the texture.
*
* <p>The texture target is derived from the
* <code>EGL_TEXTURE_TARGET</code> attribute of
* <code>surface</code>. If the attribute value is
* <code>EGL_TEXTURE_2D</code>, then buffer defines a texture for
* the two-dimensional texture object which is bound to the current
* context (hereafter referred to as the current texture object).
*
* <p>If <code>display</code> and <code>surface</code> are the
* display and surface for the calling thread�s current context,
* <code>eglBindTexImage</code> performs an implicit
* <code>glFlush</code>. For other surfaces,
* <code>eglBindTexImage</code> waits for all effects from
* previously issued OpenGL ES commands drawing to the surface to
* complete before defining the texture image, as though
* <code>glFinish</code> were called on the last context to which
* that surface were bound.
*
* <p>After <code>eglBindTexImage</code> is called, the specified
* surface is no longer available for reading or writing. Any read
* operation, such as <code>glReadPixels</code> or
* <code>eglCopyBuffers</code>, which reads values from any of the
* surface�s color buffers or ancillary buffers will produce
* indeterminate results. In addition, draw operations that are done
* to the surface before its color buffer is released from the
* texture produce indeterminate results. Specifically, if the
* surface is current to a context and thread then rendering
* commands will be processed and the context state will be updated,
* but the surface may or may not be written.
*
* <p>Texture mipmap levels are automatically generated when all of
* the following conditions are met while calling
* <code>eglBindTexImage</code>:
*
* <p>The <code>EGL_MIPMAP_TEXTURE</code> attribute of the pbuffer
* being bound is <code>EGL_TRUE</code>.
*
* <p>The OpenGL ES texture parameter
* <code>GL_GENERATE_MIPMAP</code> is <code>GL_TRUE</code> for the
* currently bound texture.
*
* <p>The value of the <code>EGL_MIPMAP_LEVEL</code> attribute of
* the pbuffer being bound is equal to the value of the texture
* parameter <code>GL_TEXTURE_BASE_LEVEL</code>. In this case,
* additional mipmap levels are generated as described in section
* 3.8 of the OpenGL ES 1.1 Specification.
*
* <h4>Notes</h4>
*
* <p><code>eglSwapBuffers</code> has no effect if it is called on
* a bound surface.
*
* <p>Any existing images associated with the different mipmap
* levels of the texture object are freed (it is as if
* <code>glTexImage</code> was called with an image of zero width).
*
* <p>The color buffer is bound to a texture object. If the texture
* object is shared between contexts, then the color buffer is also
* shared. If a texture object is deleted before
* <code>eglReleaseTexImage</code> is called, then the color buffer
* is released and the surface is made available for reading and
* writing.
*
* <p>It is not an error to call <code>glTexImage2D</code> or
* <code>glCopyTexImage2D</code> to replace an image of a texture
* object that has a color buffer bound to it. However, these calls
* will cause the color buffer to be released back to the surface
* and new memory will be allocated for the texture. Note that the
* color buffer is released even if the image that is being defined
* is a mipmap level that was not defined by the color buffer.
*
* <p><code>eglBindTexImage</code> is ignored if there is no
* current rendering context.
*
* <h4>Errors</h4>
*
* <p><code>EGL_BAD_MATCH</code> is generated if the surface
* attribute <code>EGL_TEXTURE_FORMAT</code> is set to
* <code>EGL_NO_TEXTURE</code>.
*
* <p><code>EGL_BAD_ACCESS</code> is generated if
* <code>buffer</code> is already bound to a texture.
*
* <p><code>EGL_BAD_VALUE</code> is generated if
* <code>buffer</code> is not a valid buffer (currently only
* <code>EGL_BACK_BUFFER</code> may be specified).
*
* <p><code>EGL_BAD_SURFACE</code> is generated if surface is not
* an EGL surface, or is not a pbuffer surface supporting texture
* binding.
*
* @param display Specifies the EGL display connection.
* @param surface Specifies the EGL surface.
* @param buffer Specifies the texture image data.
*
* @return <code>true</code> if the operation succeeds.
*
* @exception IllegalArgumentException if <code>display</code> is
* <code>null</code>.
* @exception IllegalArgumentException if <code>surface</code> is
* <code>null</code>.
*/
boolean eglBindTexImage(EGLDisplay display,
EGLSurface surface,
int buffer);
/**
* (EGL 1.1 only) Releases a color buffer that is being used as a
* texture.
*
* <p>The specified color buffer is released back to the
* surface. The surface is made available for reading and writing
* when it no longer has any color buffers bound as textures.
*
* <h4>Notes</h4>
*
* <p>If the specified color buffer is no longer bound to a texture
* (e.g., because the texture object was deleted) then
* <code>eglReleaseTexImage</code> has no effect. No error is
* generated.
*
* <p>The contents of the color buffer are undefined when it is
* first released. In particular, there is no guarantee that the
* texture image is still present. However, the contents of other
* color buffers are unaffected by this call. Also, the contents of
* the depth and stencil buffers are not affected by
* <code>eglBindTexImage</code> and <code>eglReleaseTexImage</code>.
*
* <p>After a color buffer is released from a texture (either
* explicitly by calling <code>eglReleaseTexImage</code> or
* implicitly by calling a routine such as
* <code>glTexImage2D</code>), all texture images that were defined
* by the color buffer become NULL (it is as if
* <code>glTexImage</code> was called with an image of zero width).
*
* <h4>Errors</h4>
*
* <p><code>EGL_BAD_MATCH</code> is generated if the surface
* attribute <code>EGL_TEXTURE_FORMAT</code> is set to
* <code>EGL_NO_TEXTURE</code>.
*
* <p><code>EGL_BAD_VALUE</code> is generated if <code>buffer</code>
* is not a valid buffer (currently only
* <code>EGL_BACK_BUFFER</code> may be specified).
*
* <p><code>EGL_BAD_SURFACE</code> is generated if
* <code>surface</code> is not an EGL surface, or is not a bound
* pbuffer surface.
*
* @param display Specifies the EGL display connection.
* @param surface Specifies the EGL surface.
* @param buffer Specifies the texture image data.
*
* @return <code>true</code> if the operation succeeds.
*
* @exception IllegalArgumentException if <code>display</code> is
* <code>null</code>.
* @exception IllegalArgumentException if <code>surface</code> is
* <code>null</code>.
*/
boolean eglReleaseTexImage(EGLDisplay display,
EGLSurface surface,
int buffer);
/**
* (EGL 1.1 only) Specifies the minimum number of video frame
* periods per buffer swap for the window associated with the
* current context.
*
* <p>The interval takes effect when <code>eglSwapBuffers</code> is
* first called subsequent to the <code>eglSwapInterval</code> call.
*
* <p>The interval specified by the function applies to the draw
* surface bound to the context that is current on the calling
* thread.
*
* <p>If <code>interval</code> is set to a value of 0, buffer swaps
* are not synchronized to a video frame, and the swap happens as
* soon as the render is complete. <code>interval</code> is silently
* clamped to minimum and maximum implementation dependent
* values before being stored; these values are defined by
* <code>EGLConfig</code> attributes
* <code>EGL_MIN_SWAP_INTERVAL</code> and
* <code>EGL_MAX_SWAP_INTERVAL</code> respectively.
*
* <h4>Notes</h4>
*
* <p>The swap interval has no effect on
* <code>eglCopyBuffers</code>.
*
* <p>The default swap interval is 1.
*
* <h4>Errors</h4>
*
* <p><code>false</code> is returned on failure, <code>true</code>
* otherwise.
*
* <p><code>EGL_BAD_CONTEXT</code> is generated if there is no
* current context on the calling thread.
*
* <p><code>EGL_BAD_SURFACE</code> is generated if there is no
* surface bound to the current context.
*
* @param display Specifies the EGL display connection.
* @param interval Specifies the minimum number of video frames that
* are displayed before a buffer swap will occur.
*
* @return <code>true</code> if the operation succeeds.
*
* @exception IllegalArgumentException if <code>display</code> is
* <code>null</code>.
*/
boolean eglSwapInterval(EGLDisplay display, int interval);
}