001: /*
002: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
004: *
005: * This program is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU General Public License version
007: * 2 only, as published by the Free Software Foundation.
008: *
009: * This program is distributed in the hope that it will be useful, but
010: * WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * General Public License version 2 for more details (a copy is
013: * included at /legal/license.txt).
014: *
015: * You should have received a copy of the GNU General Public License
016: * version 2 along with this work; if not, write to the Free Software
017: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
018: * 02110-1301 USA
019: *
020: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
021: * Clara, CA 95054 or visit www.sun.com if you need additional
022: * information or have any questions.
023: */
024:
025: package javax.microedition.khronos.egl;
026:
027: /**
028: * The EGL11 interface contains the Java(TM) programming language
029: * bindings for EGL 1.1. It extends the EGL10 interface.
030: *
031: * <p> The documentation in this interface is normative with respect
032: * to instance variable names and values, method names and signatures,
033: * and exception behavior. The remaining documentation is placed here
034: * for convenience and does not replace the normative documentation
035: * found in the EGL specification and relevant
036: * extension specifications. EGL documentation is available at the <a
037: * href="http://www.khronos.org/opengles/spec">Khronos</a> web site.
038: */
039: public interface EGL11 extends EGL10 {
040:
041: /** EGL 1.1 constant. */
042: public static final int EGL_CONTEXT_LOST = 0x300E;
043:
044: /** EGL 1.1 constant. */
045: public static final int EGL_BIND_TO_TEXTURE_RGB = 0x3039;
046: /** EGL 1.1 constant. */
047: public static final int EGL_BIND_TO_TEXTURE_RGBA = 0x303A;
048: /** EGL 1.1 constant. */
049: public static final int EGL_MIN_SWAP_INTERVAL = 0x303B;
050: /** EGL 1.1 constant. */
051: public static final int EGL_MAX_SWAP_INTERVAL = 0x303C;
052:
053: /** EGL 1.1 constant. */
054: public static final int EGL_NO_TEXTURE = 0x305C;
055: /** EGL 1.1 constant. */
056: public static final int EGL_TEXTURE_RGB = 0x305D;
057: /** EGL 1.1 constant. */
058: public static final int EGL_TEXTURE_RGBA = 0x305E;
059: /** EGL 1.1 constant. */
060: public static final int EGL_TEXTURE_2D = 0x305F;
061:
062: // Surface attributes
063:
064: /** EGL 1.1 constant. */
065: public static final int EGL_TEXTURE_FORMAT = 0x3080;
066: /** EGL 1.1 constant. */
067: public static final int EGL_TEXTURE_TARGET = 0x3081;
068: /** EGL 1.1 constant. */
069: public static final int EGL_MIPMAP_TEXTURE = 0x3082;
070: /** EGL 1.1 constant. */
071: public static final int EGL_MIPMAP_LEVEL = 0x3083;
072:
073: // BindTexImage / ReleaseTexImage buffer target
074: /** EGL 1.1 constant. */
075: public static final int EGL_BACK_BUFFER = 0x3084;
076:
077: /**
078: * (EGL 1.1 only) Set an EGL surface attribute.
079: *
080: * <p><code>eglSurfaceAttrib</code> sets the value of
081: * <code>attribute</code> for <code>surface</code> to
082: * <code>value</code>. <code>attribute</code> can be one of the
083: * following:
084: *
085: * <ul>
086: *
087: * <li><code>EGL_MIPMAP_LEVEL</code></li>
088: *
089: * <p>For mipmap textures, the <code>EGL_MIPMAP_LEVEL</code>
090: * attribute indicates which level of the mipmap should be
091: * rendered. If the value of this attribute is outside the range of
092: * supported mipmap levels, the closest valid mipmap level is
093: * selected for rendering. The default value is 0.
094: *
095: * </ul>
096: *
097: * <h4>Notes</h4>
098: *
099: * <p>If the value of pbuffer attribute
100: * <code>EGL_TEXTURE_FORMAT</code> is <code>EGL_NO_TEXTURE</code>,
101: * if the value of attribute <code>EGL_TEXTURE_TYPE</code> is
102: * <code>EGL_NO_TEXTURE</code>, or if surface is not a pbuffer, then
103: * attribute <code>EGL_MIPMAP_LEVEL</code> may be set, but has no
104: * effect.
105: *
106: * <h4>Errors</h4>
107: *
108: * <p><code>false</code> is returned on failure, <code>true</code>
109: * otherwise.
110: *
111: * <p><code>EGL_BAD_DISPLAY</code> is generated if
112: * <code>display</code> is not an EGL display connection.
113: *
114: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
115: * <code>display</code> has not been initialized.
116: *
117: * <p><code>EGL_BAD_SURFACE</code> is generated if
118: * <code>surface</code> is not an EGL surface.
119: *
120: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
121: * <code>attribute</code> is not a valid surface attribute.
122: *
123: * @param display Specifies the EGL display connection.
124: * @param surface Specifies the EGL surface.
125: * @param attribute Specifies the EGL surface attribute to set.
126: * @param value Specifies the attributes required value.
127: *
128: * @exception IllegalArgumentException if <code>display</code> is
129: * <code>null</code>.
130: * @exception IllegalArgumentException if <code>surface</code> is
131: * <code>null</code>.
132: *
133: * @return <code>true</code> if the operation succeeds.
134: */
135: boolean eglSurfaceAttrib(EGLDisplay display, EGLSurface surface,
136: int attribute, int value);
137:
138: /**
139: * (EGL 1.1 only) Defines a two-dimensional texture image.
140: *
141: * <p>The texture image consists of the image data in
142: * <code>buffer</code> for the specified <code>surface</code>, and
143: * need not be copied.
144: *
145: * <p>The texture target, the texture format and the size of the
146: * texture components are derived from attributes of the specified
147: * surface, which must be a pbuffer supporting one of the
148: * <code>EGL_BIND_TO_TEXTURE_RGB</code> or
149: * <code>EGL_BIND_TO_TEXTURE_RGBA</code> attributes.
150: *
151: * <p>The pbuffer attribute <code>EGL_TEXTURE_FORMAT</code>
152: * determines the base internal format of the texture.
153: *
154: * <p>The texture target is derived from the
155: * <code>EGL_TEXTURE_TARGET</code> attribute of
156: * <code>surface</code>. If the attribute value is
157: * <code>EGL_TEXTURE_2D</code>, then buffer defines a texture for
158: * the two-dimensional texture object which is bound to the current
159: * context (hereafter referred to as the current texture object).
160: *
161: * <p>If <code>display</code> and <code>surface</code> are the
162: * display and surface for the calling thread’s current context,
163: * <code>eglBindTexImage</code> performs an implicit
164: * <code>glFlush</code>. For other surfaces,
165: * <code>eglBindTexImage</code> waits for all effects from
166: * previously issued OpenGL ES commands drawing to the surface to
167: * complete before defining the texture image, as though
168: * <code>glFinish</code> were called on the last context to which
169: * that surface were bound.
170: *
171: * <p>After <code>eglBindTexImage</code> is called, the specified
172: * surface is no longer available for reading or writing. Any read
173: * operation, such as <code>glReadPixels</code> or
174: * <code>eglCopyBuffers</code>, which reads values from any of the
175: * surface’s color buffers or ancillary buffers will produce
176: * indeterminate results. In addition, draw operations that are done
177: * to the surface before its color buffer is released from the
178: * texture produce indeterminate results. Specifically, if the
179: * surface is current to a context and thread then rendering
180: * commands will be processed and the context state will be updated,
181: * but the surface may or may not be written.
182: *
183: * <p>Texture mipmap levels are automatically generated when all of
184: * the following conditions are met while calling
185: * <code>eglBindTexImage</code>:
186: *
187: * <p>The <code>EGL_MIPMAP_TEXTURE</code> attribute of the pbuffer
188: * being bound is <code>EGL_TRUE</code>.
189: *
190: * <p>The OpenGL ES texture parameter
191: * <code>GL_GENERATE_MIPMAP</code> is <code>GL_TRUE</code> for the
192: * currently bound texture.
193: *
194: * <p>The value of the <code>EGL_MIPMAP_LEVEL</code> attribute of
195: * the pbuffer being bound is equal to the value of the texture
196: * parameter <code>GL_TEXTURE_BASE_LEVEL</code>. In this case,
197: * additional mipmap levels are generated as described in section
198: * 3.8 of the OpenGL ES 1.1 Specification.
199: *
200: * <h4>Notes</h4>
201: *
202: * <p><code>eglSwapBuffers</code> has no effect if it is called on
203: * a bound surface.
204: *
205: * <p>Any existing images associated with the different mipmap
206: * levels of the texture object are freed (it is as if
207: * <code>glTexImage</code> was called with an image of zero width).
208: *
209: * <p>The color buffer is bound to a texture object. If the texture
210: * object is shared between contexts, then the color buffer is also
211: * shared. If a texture object is deleted before
212: * <code>eglReleaseTexImage</code> is called, then the color buffer
213: * is released and the surface is made available for reading and
214: * writing.
215: *
216: * <p>It is not an error to call <code>glTexImage2D</code> or
217: * <code>glCopyTexImage2D</code> to replace an image of a texture
218: * object that has a color buffer bound to it. However, these calls
219: * will cause the color buffer to be released back to the surface
220: * and new memory will be allocated for the texture. Note that the
221: * color buffer is released even if the image that is being defined
222: * is a mipmap level that was not defined by the color buffer.
223: *
224: * <p><code>eglBindTexImage</code> is ignored if there is no
225: * current rendering context.
226: *
227: * <h4>Errors</h4>
228: *
229: * <p><code>EGL_BAD_MATCH</code> is generated if the surface
230: * attribute <code>EGL_TEXTURE_FORMAT</code> is set to
231: * <code>EGL_NO_TEXTURE</code>.
232: *
233: * <p><code>EGL_BAD_ACCESS</code> is generated if
234: * <code>buffer</code> is already bound to a texture.
235: *
236: * <p><code>EGL_BAD_VALUE</code> is generated if
237: * <code>buffer</code> is not a valid buffer (currently only
238: * <code>EGL_BACK_BUFFER</code> may be specified).
239: *
240: * <p><code>EGL_BAD_SURFACE</code> is generated if surface is not
241: * an EGL surface, or is not a pbuffer surface supporting texture
242: * binding.
243: *
244: * @param display Specifies the EGL display connection.
245: * @param surface Specifies the EGL surface.
246: * @param buffer Specifies the texture image data.
247: *
248: * @return <code>true</code> if the operation succeeds.
249: *
250: * @exception IllegalArgumentException if <code>display</code> is
251: * <code>null</code>.
252: * @exception IllegalArgumentException if <code>surface</code> is
253: * <code>null</code>.
254: */
255: boolean eglBindTexImage(EGLDisplay display, EGLSurface surface,
256: int buffer);
257:
258: /**
259: * (EGL 1.1 only) Releases a color buffer that is being used as a
260: * texture.
261: *
262: * <p>The specified color buffer is released back to the
263: * surface. The surface is made available for reading and writing
264: * when it no longer has any color buffers bound as textures.
265: *
266: * <h4>Notes</h4>
267: *
268: * <p>If the specified color buffer is no longer bound to a texture
269: * (e.g., because the texture object was deleted) then
270: * <code>eglReleaseTexImage</code> has no effect. No error is
271: * generated.
272: *
273: * <p>The contents of the color buffer are undefined when it is
274: * first released. In particular, there is no guarantee that the
275: * texture image is still present. However, the contents of other
276: * color buffers are unaffected by this call. Also, the contents of
277: * the depth and stencil buffers are not affected by
278: * <code>eglBindTexImage</code> and <code>eglReleaseTexImage</code>.
279: *
280: * <p>After a color buffer is released from a texture (either
281: * explicitly by calling <code>eglReleaseTexImage</code> or
282: * implicitly by calling a routine such as
283: * <code>glTexImage2D</code>), all texture images that were defined
284: * by the color buffer become NULL (it is as if
285: * <code>glTexImage</code> was called with an image of zero width).
286: *
287: * <h4>Errors</h4>
288: *
289: * <p><code>EGL_BAD_MATCH</code> is generated if the surface
290: * attribute <code>EGL_TEXTURE_FORMAT</code> is set to
291: * <code>EGL_NO_TEXTURE</code>.
292: *
293: * <p><code>EGL_BAD_VALUE</code> is generated if <code>buffer</code>
294: * is not a valid buffer (currently only
295: * <code>EGL_BACK_BUFFER</code> may be specified).
296: *
297: * <p><code>EGL_BAD_SURFACE</code> is generated if
298: * <code>surface</code> is not an EGL surface, or is not a bound
299: * pbuffer surface.
300: *
301: * @param display Specifies the EGL display connection.
302: * @param surface Specifies the EGL surface.
303: * @param buffer Specifies the texture image data.
304: *
305: * @return <code>true</code> if the operation succeeds.
306: *
307: * @exception IllegalArgumentException if <code>display</code> is
308: * <code>null</code>.
309: * @exception IllegalArgumentException if <code>surface</code> is
310: * <code>null</code>.
311: */
312: boolean eglReleaseTexImage(EGLDisplay display, EGLSurface surface,
313: int buffer);
314:
315: /**
316: * (EGL 1.1 only) Specifies the minimum number of video frame
317: * periods per buffer swap for the window associated with the
318: * current context.
319: *
320: * <p>The interval takes effect when <code>eglSwapBuffers</code> is
321: * first called subsequent to the <code>eglSwapInterval</code> call.
322: *
323: * <p>The interval specified by the function applies to the draw
324: * surface bound to the context that is current on the calling
325: * thread.
326: *
327: * <p>If <code>interval</code> is set to a value of 0, buffer swaps
328: * are not synchronized to a video frame, and the swap happens as
329: * soon as the render is complete. <code>interval</code> is silently
330: * clamped to minimum and maximum implementation dependent
331: * values before being stored; these values are defined by
332: * <code>EGLConfig</code> attributes
333: * <code>EGL_MIN_SWAP_INTERVAL</code> and
334: * <code>EGL_MAX_SWAP_INTERVAL</code> respectively.
335: *
336: * <h4>Notes</h4>
337: *
338: * <p>The swap interval has no effect on
339: * <code>eglCopyBuffers</code>.
340: *
341: * <p>The default swap interval is 1.
342: *
343: * <h4>Errors</h4>
344: *
345: * <p><code>false</code> is returned on failure, <code>true</code>
346: * otherwise.
347: *
348: * <p><code>EGL_BAD_CONTEXT</code> is generated if there is no
349: * current context on the calling thread.
350: *
351: * <p><code>EGL_BAD_SURFACE</code> is generated if there is no
352: * surface bound to the current context.
353: *
354: * @param display Specifies the EGL display connection.
355: * @param interval Specifies the minimum number of video frames that
356: * are displayed before a buffer swap will occur.
357: *
358: * @return <code>true</code> if the operation succeeds.
359: *
360: * @exception IllegalArgumentException if <code>display</code> is
361: * <code>null</code>.
362: */
363: boolean eglSwapInterval(EGLDisplay display, int interval);
364: }
|