0001: /*
0002: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
0003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
0004: *
0005: * This program is free software; you can redistribute it and/or
0006: * modify it under the terms of the GNU General Public License version
0007: * 2 only, as published by the Free Software Foundation.
0008: *
0009: * This program is distributed in the hope that it will be useful, but
0010: * WITHOUT ANY WARRANTY; without even the implied warranty of
0011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
0012: * General Public License version 2 for more details (a copy is
0013: * included at /legal/license.txt).
0014: *
0015: * You should have received a copy of the GNU General Public License
0016: * version 2 along with this work; if not, write to the Free Software
0017: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
0018: * 02110-1301 USA
0019: *
0020: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
0021: * Clara, CA 95054 or visit www.sun.com if you need additional
0022: * information or have any questions.
0023: */
0024:
0025: package javax.microedition.khronos.egl;
0026:
0027: /**
0028: * The EGL10 interface contains the Java(TM) programming language
0029: * bindings for EGL 1.0.
0030: *
0031: * <p> The documentation in this interface is normative with respect
0032: * to instance variable names and values, method names and signatures,
0033: * and exception behavior. The remaining documentation is placed here
0034: * for convenience and does not replace the normative documentation
0035: * found in the EGL specification and relevant
0036: * extension specifications. EGL documentation is available at the <a
0037: * href="http://www.khronos.org/opengles/spec">Khronos</a> web site.
0038: *
0039: * <p>Extensions may return values or allow arguments to take on
0040: * values other than those listed in this specification.
0041: * Implementations that provide a given extension must pass such values
0042: * to and from the underlying engine.
0043: *
0044: * <p>If a method throws an exception, the state of the underlying EGL
0045: * engine is left intact.
0046: *
0047: * <p> All OpenGL ES drawing (except to Pbuffer surfaces) must be
0048: * preceded by a call to
0049: * <code>eglWaitNative(EGL10.EGL_CORE_NATIVE_ENGINE, target)</code>
0050: * where <code>target</code> is a platform-specific object describing
0051: * the rendering target,
0052: * and followed by a call to <code>eglWaitGL()</code>. Between these
0053: * calls, the results of calls or calls to any other drawing API, such
0054: * as MIDP, JSR 184, <code>java.awt</code>, etc., are undefined. When
0055: * drawing to an image, the results are not guaranteed to appear in
0056: * the image pixels until <code>eglWaitGL</code> has returned.
0057: *
0058: * <p> It is not required that calls to methods of this interface be
0059: * mapped one-to-one onto calls to functions in the underlying EGL
0060: * implementation. Implementations may contain logic to manage
0061: * configurations, drawing surface access, threading issues, etc., as
0062: * required in order to integrate EGL-based APIs with other platform
0063: * drawing APIs. For example, an implementation that makes use of a
0064: * software back buffer may translate a call to
0065: * <code>EGL10.eglCreateWindowSurface</code> into a call to the native
0066: * function <code>eglCreatePixmapSurface</code> targetting the
0067: * buffer. Naturally, hardware-accelerated implementations should
0068: * endeavor to avoid such workarounds.
0069: *
0070: * <h4>Drawing to a Pbuffer</h4>
0071: *
0072: * <p> A Pbuffer is an invisible, possibly hardware-accelerated
0073: * buffer. Pbuffer surfaces are created using the
0074: * <code>EGL10.eglCreatePbufferSurface</code> method. Pbuffers are
0075: * accessible only from EGL-based APIs, and follow the rules set out
0076: * in the EGL specification. Pbuffers may be used in the same manner
0077: * on any Java platform.
0078: *
0079: * <p>The integration between EGL and specific Java ME platforms is as
0080: * follows.
0081: *
0082: * <h3>CLDC/MIDP</h3>
0083: *
0084: * <p>On the CLDC/MIDP platform, drawing can be performed to four
0085: * types of targets: <code>javax.microedition.lcdui.Canvas</code>,
0086: * <code>javax.microedition.lcdui.game.GameCanvas</code>, (mutable)
0087: * <code>javax.microedition.lcdui.Image</code>,
0088: * <!-- <code>javax.microedition.khronos.egl.EGLCanvas</code>,--> or to a
0089: * Pbuffer.
0090: *
0091: * <p>The <code>EGL_DEFAULT_DISPLAY</code> token is used to
0092: * specify a display.
0093: *
0094: * <h4>Drawing to a <code>Canvas</code> or <code>GameCanvas</code></h4>
0095: *
0096: * <p> A <code>Canvas</code> or <code>GameCanvas</code> is specified
0097: * as a drawing target using the <code>eglCreateWindowSurface</code>
0098: * method. The <code>native_window</code> argument must be an
0099: * instance of <code>javax.microedition.lcdui.Graphics</code> that was
0100: * obtained directly from the argument to the
0101: * <code>Canvas.paint()</code> method or from the
0102: * <code>GameCanvas.getGraphics()</code> method. A
0103: * <code>Graphics</code> instance obtained from the argument to
0104: * <code>Canvas.paint</code> may be reused in subsequent
0105: * <code>paint</code> calls targeting the same <code>Canvas</code>.
0106: *
0107: * <p> Drawing to a <code>Canvas</code> or <code>GameCanvas</code>
0108: * allows for mixing of different drawing APIs.
0109: *
0110: * <p> When drawing to a <code>Canvas</code> (that is not a
0111: * <code>GameCanvas</code>), drawing must take place entirely within
0112: * the scope of a system-generated call to the <code>Canvas</code>'s
0113: * <code>paint(Graphics)</code> method. The results of drawing to a
0114: * <code>Canvas</code> outside the scope of such a call are undefined.
0115: *
0116: * <p> Calling <code>eglSwapBuffers</code> is equivalent to calling
0117: * <code>glFinish</code>, and does not affect the screen output. The
0118: * normal <code>GameCanvas.flushGraphics</code> method is used to
0119: * control screen output.
0120: *
0121: * <p> The initial contents of the back buffer for a
0122: * <code>GameCanvas</code> are initialized to white, and calls to
0123: * <code>flushGraphics</code> do not alter the buffer contents.
0124: *
0125: * <pre>
0126: * import javax.microedition.lcdui.Display;
0127: * import javax.microedition.lcdui.Graphics;
0128: * import javax.microedition.lcdui.game.GameCanvas;
0129: * import javax.microedition.midlet.MIDlet;
0130: * import javax.microedition.khronos.egl.*;
0131: * import javax.microedition.khronos.opengles.*;
0132: *
0133: * class MyGameCanvas extends GameCanvas {
0134: * EGL11 egl;
0135: * GL11 gl;
0136: * Graphics midpGraphics;
0137: * javax.microedition.m3g.Graphics3D m3gContext;
0138: *
0139: * MyGameCanvas(MIDlet thisMIDlet) {
0140: * // This example doesn't require key events
0141: * super(true);
0142: *
0143: * // Get a Graphics instance for MIDP rendering
0144: * // and to use in createWindowSurface
0145: * this.midpGraphics = getGraphics();
0146: *
0147: * // Show this GameCanvas on the display
0148: * Display display = Display.getDisplay(thisMIDlet);
0149: * display.setCurrent(this);
0150: *
0151: * // Create an EGL instance
0152: * this.egl = (EGL11)EGLContext.getEGL();
0153: *
0154: * // Get the EGL display object and initialize EGL
0155: * EGLDisplay eglDisplay = egl.eglGetDisplay(EGL11.EGL_DEFAULT_DISPLAY);
0156: * int[] major_minor = new int[2];
0157: * egl.eglInitialize(eglDisplay, major_minor);
0158: * System.out.println("EGL revision: major = " + major_minor[0]);
0159: * System.out.println("EGL revision: minor = " + major_minor[1]);
0160: *
0161: * // Determine the number of available configurations
0162: * int[] num_config = new int[1];
0163: * egl.eglGetConfigs(eglDisplay, null, 0, num_config);
0164: * System.out.println("There are " + num_config[0] + " configurations");
0165: *
0166: * // Locate an 8/8/8 RGB configuration
0167: * int[] configAttrs = { EGL11.EGL_RED_SIZE, 8,
0168: * EGL11.EGL_GREEN_SIZE, 8,
0169: * EGL11.EGL_BLUE_SIZE, 8,
0170: * EGL11.EGL_ALPHA_SIZE, EGL11.EGL_DONT_CARE,
0171: * EGL11.EGL_DEPTH_SIZE, EGL11.EGL_DONT_CARE,
0172: * EGL11.EGL_STENCIL_SIZE, EGL11.EGL_DONT_CARE,
0173: * EGL11.EGL_NONE
0174: * };
0175: *
0176: * // Grab the first matching config
0177: * EGLConfig[] eglConfigs = new EGLConfig[1];
0178: * egl.eglChooseConfig(eglDisplay, configAttrs,
0179: * eglConfigs, 1, num_config);
0180: * EGLConfig eglConfig = eglConfigs[0];
0181: *
0182: * // Get a context for EGL rendering
0183: * EGLContext eglContext =
0184: * egl.eglCreateContext(eglDisplay, eglConfig,
0185: * EGL11.EGL_NO_CONTEXT, null);
0186: *
0187: * // Get a GL object for rendering
0188: * this.gl = (GL11)eglContext.getGL();
0189: *
0190: * // Bind a window surface to the context
0191: * EGLSurface eglSurface =
0192: * egl.eglCreateWindowSurface(eglDisplay, eglConfig, midpGraphics, null);
0193:
0194: * // Make the context current for future GL calls
0195: * egl.eglMakeCurrent(eglDisplay, eglSurface, eglSurface, eglContext);
0196: *
0197: * // Get a context for M3G rendering
0198: * this.m3g = ...;
0199: * }
0200: *
0201: * // The update loop
0202: * public void run() {
0203: * while (true) {
0204: * // Do some MIDP 2D rendering
0205: * // Use of OpenGL ES or M3G is not allowed here
0206: * // MIDP primitives drawn here will appear underneath the
0207: * // OpenGL ES drawing
0208: * midpGraphics.drawLine(...);
0209: *
0210: * // Wait for MIDP drawing to complete
0211: * egl.eglWaitNative(EGL11.EGL_CORE_NATIVE_ENGINE, midpGraphics);
0212: * // Now it is O.K. to use OpenGL ES drawing APIs
0213: *
0214: * // Do some OpenGL ES rendering
0215: * // Use of MIDP, JSR 184, or other drawing APIs is undefined here
0216: * gl.glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
0217: * gl.glClear(GL11.GL_COLOR_BUFFER_BIT | GL11.GL_DEPTH_BUFFER_BIT);
0218: * gl.glFrustumf(...);
0219: * // etc.
0220: *
0221: * // Wait for OpenGL ES rendering to complete
0222: * egl.eglWaitGL();
0223: * // Now it is O.K. to use MIDP drawing APIs
0224: *
0225: * // MIDP primitives drawn here will appear on top of the
0226: * // OpenGL ES drawing
0227: * midpGraphics.drawRect(...);
0228: *
0229: * // Do some M3G (JSR 184) rendering
0230: * m3g.bindTarget(midpGraphics, ...);
0231: * // Now it is O.K. to use M3G, but not MIDP or OpenGL ES
0232: *
0233: * // M3G commands go here
0234: *
0235: * // Wait for M3G drawing to complete
0236: * m3g.releaseTarget();
0237: * // Now it is O.K. to use MIDP drawing APIs
0238: *
0239: * // Do some more MIDP 2D rendering
0240: * // MIDP primitives drawn here will appear on top of the
0241: * // OpenGL ES and M3G drawings
0242: * midp_graphics.drawArc(...);
0243: *
0244: * // Flush the back buffer to the screen
0245: * flushGraphics();
0246: * }
0247: * }
0248: * }
0249: * </pre>
0250: *
0251: * <h4>Drawing to an <code>Image</code></h4>
0252: *
0253: * <p> The <code>eglCreatePixmapSurface</code> method allows drawing
0254: * to an <code>Image</code>. The <code>Image</code> must be mutable.
0255: * The <code>native_pixmap</code> argument must be an instance of
0256: * <code>javax.microedition.lcdui.Graphics</code> that was obtained
0257: * from the <code>Image</code>'s <code>getGraphics()</code> method.
0258: *
0259: * <p> OpenGL ES drawing must be bracketed between calls to
0260: * <code>eglWaitNative</code> and <code>eglWaitGL</code> in the same
0261: * manner as for <code>Canvas</code> and <code>GameCanvas</code>.
0262: * Calling <code>eglSwapBuffers</code> is equivalent to calling
0263: * <code>glFinish</code>, since there is no back buffer.
0264: *
0265: * <!--
0266: * <h4>Drawing to an <code>EGLCanvas</code></h4>
0267: *
0268: * <p> <code>EGLCanvas</code> maximizes the potential for efficiency
0269: * by removing the requirement to allow non-OpenGL ES drawing. The
0270: * results of drawing to an <code>EGLCanvas</code> using other non-EGL
0271: * based APIs such as MIDP and JSR 184 is undefined.
0272: *
0273: * <p> An <code>EGLCanvas</code> is specified as a drawing target
0274: * using the <code>eglCreateWindowSurface</code> method. The
0275: * <code>native_window</code> argument must be an instance of
0276: * <code>javax.microedition.lcdui.Graphics</code> that was obtained
0277: * directly from the <code>EGLCanvas.getGraphics()</code> method.
0278: *
0279: * <p> When an <code>EGLCanvas</code> is set using the
0280: * <code>Display.setCurrent</code> method, it occupies as much of the
0281: * screen as is allowed by the platform (leaving room for a status bar
0282: * if the platform requires one). OpenGL ES drawing is performed to a
0283: * back buffer, the contents of which are initially undefined. When
0284: * drawing is complete, a call to <code>eglSwapBuffers</code> causes
0285: * the contents of the back buffer to be copied to the
0286: * screen. Following the call, the back buffer contents are once again
0287: * undefined.
0288: * -->
0289: *
0290: * <h3>Other platforms</h3>
0291: *
0292: * <p> The current specification does not address AWT-based platforms
0293: * such as CDC/Personal Basis Profile, CDC/Personal Profile,
0294: * and Java Standard Edition. The details of how to bind to displays
0295: * and surfaces on these platforms will be provided in a future release
0296: * of the specification.
0297: */
0298: public interface EGL10 extends EGL {
0299:
0300: /**
0301: * An object that is used as an argument to
0302: * <code>eglGetDisplay</code> to indicate that the defalt display of
0303: * the device is to be used.
0304: */
0305: public static final Object EGL_DEFAULT_DISPLAY = new Object();
0306:
0307: /**
0308: * An <code>EGLContext</code> object used to indicate a null context.
0309: */
0310: public static final EGLContext EGL_NO_CONTEXT = EGLContextImpl
0311: .getInstance(0);
0312:
0313: /**
0314: * An <code>EGLContext</code> object used to indicate a null display.
0315: */
0316: public static final EGLDisplay EGL_NO_DISPLAY = EGLDisplayImpl
0317: .getInstance(0);
0318:
0319: /**
0320: * An <code>EGLContext</code> object used to indicate a null surface.
0321: */
0322: public static final EGLSurface EGL_NO_SURFACE = EGLSurfaceImpl
0323: .getInstance(0); // C #define of EGL_NO_SURFACE
0324:
0325: // Boolean
0326:
0327: /**
0328: * A value corresponding to the 'EGLBoolean' false value.
0329: */
0330: public static final int EGL_FALSE = 0;
0331:
0332: /**
0333: * A value corresponding to the 'EGLBoolean' true value.
0334: */
0335: public static final int EGL_TRUE = 1;
0336:
0337: // Errors
0338:
0339: /**
0340: * EGL error code indicating success.
0341: */
0342: public static final int EGL_SUCCESS = 0x3000;
0343:
0344: /**
0345: * EGL error code indicating 'not initialized'.
0346: */
0347: public static final int EGL_NOT_INITIALIZED = 0x3001;
0348:
0349: /**
0350: * EGL error code indicating 'bad access'.
0351: */
0352: public static final int EGL_BAD_ACCESS = 0x3002;
0353:
0354: /**
0355: * EGL error code indicating 'bad alloc'.
0356: */
0357: public static final int EGL_BAD_ALLOC = 0x3003;
0358:
0359: /**
0360: * EGL error code indicating 'bad attribute'.
0361: */
0362: public static final int EGL_BAD_ATTRIBUTE = 0x3004;
0363:
0364: /**
0365: * EGL error code indicating 'bad config'.
0366: */
0367: public static final int EGL_BAD_CONFIG = 0x3005;
0368:
0369: /**
0370: * EGL error code indicating 'bad context'.
0371: */
0372: public static final int EGL_BAD_CONTEXT = 0x3006;
0373:
0374: /**
0375: * EGL error code indicating 'bad current surface'.
0376: */
0377: public static final int EGL_BAD_CURRENT_SURFACE = 0x3007;
0378:
0379: /**
0380: * EGL error code indicating 'bad display'.
0381: */
0382: public static final int EGL_BAD_DISPLAY = 0x3008;
0383:
0384: /**
0385: * EGL error code indicating 'bad match'.
0386: */
0387: public static final int EGL_BAD_MATCH = 0x3009;
0388:
0389: /**
0390: * EGL error code indicating 'bad native pixmap'.
0391: */
0392: public static final int EGL_BAD_NATIVE_PIXMAP = 0x300A;
0393:
0394: /**
0395: * EGL error code indicating 'bad native window'.
0396: */
0397: public static final int EGL_BAD_NATIVE_WINDOW = 0x300B;
0398:
0399: /**
0400: * EGL error code indicating 'bad parameter'.
0401: */
0402: public static final int EGL_BAD_PARAMETER = 0x300C;
0403:
0404: /**
0405: * EGL error code indicating 'bad surface'.
0406: */
0407: public static final int EGL_BAD_SURFACE = 0x300D;
0408:
0409: // Config attributes
0410:
0411: /**
0412: * <code>EGLConfig</code> attribute name.
0413: */
0414: public static final int EGL_BUFFER_SIZE = 0x3020;
0415:
0416: /**
0417: * <code>EGLConfig</code> attribute name.
0418: */
0419: public static final int EGL_ALPHA_SIZE = 0x3021;
0420:
0421: /**
0422: * <code>EGLConfig</code> attribute name.
0423: */
0424: public static final int EGL_BLUE_SIZE = 0x3022;
0425:
0426: /**
0427: * <code>EGLConfig</code> attribute name.
0428: */
0429: public static final int EGL_GREEN_SIZE = 0x3023;
0430:
0431: /**
0432: * <code>EGLConfig</code> attribute name.
0433: */
0434: public static final int EGL_RED_SIZE = 0x3024;
0435:
0436: /**
0437: * <code>EGLConfig</code> attribute name.
0438: */
0439: public static final int EGL_DEPTH_SIZE = 0x3025;
0440:
0441: /**
0442: * <code>EGLConfig</code> attribute name.
0443: */
0444: public static final int EGL_STENCIL_SIZE = 0x3026;
0445:
0446: /**
0447: * <code>EGLConfig</code> attribute name.
0448: */
0449: public static final int EGL_CONFIG_CAVEAT = 0x3027;
0450:
0451: /**
0452: * <code>EGLConfig</code> attribute name.
0453: */
0454: public static final int EGL_CONFIG_ID = 0x3028;
0455:
0456: /**
0457: * <code>EGLConfig</code> attribute name.
0458: */
0459: public static final int EGL_LEVEL = 0x3029;
0460:
0461: /**
0462: * <code>EGLConfig</code> attribute name.
0463: */
0464: public static final int EGL_MAX_PBUFFER_HEIGHT = 0x302A;
0465:
0466: /**
0467: * <code>EGLConfig</code> attribute name.
0468: */
0469: public static final int EGL_MAX_PBUFFER_PIXELS = 0x302B;
0470:
0471: /**
0472: * <code>EGLConfig</code> attribute name.
0473: */
0474: public static final int EGL_MAX_PBUFFER_WIDTH = 0x302C;
0475:
0476: /**
0477: * <code>EGLConfig</code> attribute name.
0478: */
0479: public static final int EGL_NATIVE_RENDERABLE = 0x302D;
0480:
0481: /**
0482: * <code>EGLConfig</code> attribute name.
0483: */
0484: public static final int EGL_NATIVE_VISUAL_ID = 0x302E;
0485:
0486: /**
0487: * <code>EGLConfig</code> attribute name.
0488: */
0489: public static final int EGL_NATIVE_VISUAL_TYPE = 0x302F;
0490:
0491: /**
0492: * <code>EGLConfig</code> attribute name.
0493: */
0494: public static final int EGL_PRESERVED_RESOURCES = 0x3030;
0495:
0496: /**
0497: * <code>EGLConfig</code> attribute name.
0498: */
0499: public static final int EGL_SAMPLES = 0x3031;
0500:
0501: /**
0502: * <code>EGLConfig</code> attribute name.
0503: */
0504: public static final int EGL_SAMPLE_BUFFERS = 0x3032;
0505:
0506: /**
0507: * <code>EGLConfig</code> attribute name.
0508: */
0509: public static final int EGL_SURFACE_TYPE = 0x3033;
0510:
0511: /**
0512: * <code>EGLConfig</code> attribute name.
0513: */
0514: public static final int EGL_TRANSPARENT_TYPE = 0x3034;
0515:
0516: /**
0517: * <code>EGLConfig</code> attribute name.
0518: */
0519: public static final int EGL_TRANSPARENT_BLUE_VALUE = 0x3035;
0520:
0521: /**
0522: * <code>EGLConfig</code> attribute name.
0523: */
0524: public static final int EGL_TRANSPARENT_GREEN_VALUE = 0x3036;
0525:
0526: /**
0527: * <code>EGLConfig</code> attribute name.
0528: */
0529: public static final int EGL_TRANSPARENT_RED_VALUE = 0x3037;
0530:
0531: // Config atribute and value
0532:
0533: /**
0534: * <code>EGLConfig</code> attribute name and value.
0535: */
0536: public static final int EGL_NONE = 0x3038;
0537:
0538: // Config values
0539:
0540: /**
0541: * <code>EGLConfig</code> attribute value.
0542: */
0543: public static final int EGL_DONT_CARE = -1;
0544:
0545: /**
0546: * <code>EGLConfig</code> attribute value.
0547: */
0548: public static final int EGL_PBUFFER_BIT = 0x01;
0549:
0550: /**
0551: * <code>EGLConfig</code> attribute value.
0552: */
0553: public static final int EGL_PIXMAP_BIT = 0x02;
0554:
0555: /**
0556: * <code>EGLConfig</code> attribute value.
0557: */
0558: public static final int EGL_WINDOW_BIT = 0x04;
0559:
0560: /**
0561: * <code>EGLConfig</code> attribute value.
0562: */
0563: public static final int EGL_SLOW_CONFIG = 0x3050;
0564:
0565: /**
0566: * <code>EGLConfig</code> attribute value.
0567: */
0568: public static final int EGL_NON_CONFORMANT_CONFIG = 0x3051;
0569:
0570: /**
0571: * <code>EGLConfig</code> attribute value.
0572: */
0573: public static final int EGL_TRANSPARENT_RGB = 0x3052;
0574:
0575: // String names
0576:
0577: /**
0578: * Constant for use in <code>eglQueryString</code>.
0579: */
0580: public static final int EGL_VENDOR = 0x3053;
0581:
0582: /**
0583: * Constant for use in <code>eglQueryString</code>.
0584: */
0585: public static final int EGL_VERSION = 0x3054;
0586:
0587: /**
0588: * Constant for use in <code>eglQueryString</code>.
0589: */
0590: public static final int EGL_EXTENSIONS = 0x3055;
0591:
0592: // Surface attributes
0593:
0594: /**
0595: * <code>EGLSurface</code> attribute name.
0596: */
0597: public static final int EGL_HEIGHT = 0x3056;
0598:
0599: /**
0600: * <code>EGLSurface</code> attribute name.
0601: */
0602: public static final int EGL_WIDTH = 0x3057;
0603:
0604: /**
0605: * <code>EGLSurface</code> attribute name.
0606: */
0607: public static final int EGL_LARGEST_PBUFFER = 0x3058;
0608:
0609: // Current surfaces
0610:
0611: /**
0612: * Constant for use in the <code>readdraw</code> argument of
0613: * <code>getCurrentSurface</code>.
0614: */
0615: public static final int EGL_DRAW = 0x3059;
0616:
0617: /**
0618: * Constant for use as the <code>readdraw</code> argument of
0619: * <code>getCurrentSurface</code>.
0620: */
0621: public static final int EGL_READ = 0x305A;
0622:
0623: // Engines
0624:
0625: /**
0626: * Constant for use as the <code>engine</code> argument of
0627: * <code>eglWaitNative</code>, indicating the core native engine of
0628: * the platform.
0629: *
0630: * <p>On a JME CLDC/MIDP platform, this specifies the MIDP/LCDUI
0631: * drawing engine.
0632: *
0633: * <!-- <p>On other JME or JSE platforms, this specifies the AWT/Java2D
0634: * drawing engine. -->
0635: */
0636: public static final int EGL_CORE_NATIVE_ENGINE = 0x305B;
0637:
0638: // Functions
0639:
0640: /**
0641: * Return error information.
0642: *
0643: * <p><code>eglGetError</code> returns the error of the last called EGL
0644: * function in the current thread. Initially, the error is set to
0645: * <code>EGL_SUCCESS</code>.
0646: *
0647: * <p>The following errors are currently defined:
0648: *
0649: * <ul>
0650: *
0651: * <li><code>EGL_SUCCESS</code></li>
0652: *
0653: * <p>The last function succeeded without error.
0654: *
0655: * <li><code>EGL_NOT_INITIALIZED</code></li>
0656: *
0657: * <p>EGL is not initialized, or could not be initialized, for the
0658: * specified EGL display connection.
0659: *
0660: * <li><code>EGL_BAD_ACCESS</code></li>
0661: *
0662: * <p>EGL cannot access a requested resource (for example a context
0663: * is bound in another thread).
0664: *
0665: * <li><code>EGL_BAD_ALLOC</code></li>
0666: *
0667: * <p>EGL failed to allocate resources for the requested operation.
0668: *
0669: * <li><code>EGL_BAD_ATTRIBUTE</code></li>
0670: *
0671: * <p>An unrecognized attribute or attribute value was passed in
0672: * the attribute list.
0673: *
0674: * <li><code>EGL_BAD_CONTEXT</code></li>
0675: *
0676: * <p>An <code>EGLContext</code> argument does not name a valid EGL
0677: * rendering context.
0678: *
0679: * <li><code>EGL_BAD_CONFIG</code></li>
0680: *
0681: * <p>An <code>EGLConfig</code> argument does not name a valid EGL
0682: * frame buffer configuration.
0683: *
0684: * <li><code>EGL_BAD_CURRENT_SURFACE</code></li>
0685: *
0686: * <p>The current surface of the calling thread is a window, pixel
0687: * buffer or pixmap that is no longer valid.
0688: *
0689: * <li><code>EGL_BAD_DISPLAY</code></li>
0690: *
0691: * <p>An <code>EGLDisplay</code> argument does not name a valid EGL
0692: * display connection.
0693: *
0694: * <li><code>EGL_BAD_SURFACE</code></li>
0695: *
0696: * <p>An <code>EGLSurface</code> argument does not name a valid
0697: * surface (window, pixel buffer or pixmap) configured for GL
0698: * rendering.
0699: *
0700: * <li><code>EGL_BAD_MATCH</code></li>
0701: *
0702: * <p>Arguments are inconsistent (for example, a valid context
0703: * requires buffers not supplied by a valid surface).
0704: *
0705: * <li><code>EGL_BAD_PARAMETER</code></li>
0706: *
0707: * <p>One or more argument values are invalid.
0708: *
0709: * <li><code>EGL_BAD_NATIVE_PIXMAP</code></li>
0710: *
0711: * <p>A <code>native_pixmap</code> argument does not refer to a
0712: * valid native pixmap.
0713: *
0714: * <li><code>EGL_BAD_NATIVE_WINDOW</code></li>
0715: *
0716: * <p>A <code>native_window</code> argument does not refer to a
0717: * valid native window.
0718: *
0719: * <li><code>EGL_CONTEXT_LOST</code> (1.1 only)</li>
0720: *
0721: * <p>A power management event has occurred. The application must
0722: * destroy all contexts and reinitialise OpenGL ES state and objects
0723: * to continue rendering.
0724: *
0725: * </ul>
0726: *
0727: * <h4>Errors</h4>
0728: *
0729: * <p>A call to <code>eglGetError</code> sets the error to
0730: * <code>EGL_SUCCESS</code>.
0731: *
0732: * @return One of <code>EGL_SUCCESS</code>,
0733: * <code>EGL_NOT_INITIALIZED</code>, <code>EGL_BAD_ACCESS</code>,
0734: * <code>EGL_BAD_ALLOC</code>, <code>EGL_BAD_ATTRIBUTE</code>,
0735: * <code>EGL_BAD_CONTEXT</code>, <code>EGL_BAD_CONFIG</code>,
0736: * <code>EGL_BAD_CURRENT_SURFACE</code>,
0737: * <code>EGL_BAD_DISPLAY</code>, <code>EGL_BAD_MATCH</code>,
0738: * <code>EGL_BAD_NATIVE_PIXMAP</code>,
0739: * <code>EGL_BAD_NATIVE_WINDOW</code>,
0740: * <code>EGL_BAD_PARAMETER</code>, <code>EGL_BAD_SURFACE</code>, or
0741: * other error code defined by an extension.
0742: */
0743: int eglGetError();
0744:
0745: /**
0746: * Return an EGL display connection.
0747: *
0748: * <p><code>eglGetDisplay</code> obtains the EGL display connection
0749: * for the native display <code>native_display</code>.
0750: *
0751: * <p>If <code>display_id</code> is
0752: * <code>EGL_DEFAULT_DISPLAY</code>, a default display connection is
0753: * returned.
0754: *
0755: * <p>If no display connection matching <code>native_display</code>
0756: * is available, <code>EGL_NO_DISPLAY</code> is returned. No error
0757: * is generated.
0758: *
0759: * <p>Use <code>eglInitialize</code> to initialize the display
0760: * connection.
0761: *
0762: * @param native_display Specifies the display to connect
0763: * to. <code>EGL_DEFAULT_DISPLAY</code> indicates the default
0764: * display.
0765: *
0766: * @return An <code>EGLDisplay</code> object.
0767: *
0768: * @exception IllegalArgumentException if <code>native_display</code> is
0769: * <code>null</code> or is not of a suitable type for the platform.
0770: *
0771: */
0772: EGLDisplay eglGetDisplay(Object native_display);
0773:
0774: /**
0775: * Initialize an EGL display connection.
0776: *
0777: * <p><code>eglInitialize</code> initializes the EGL display
0778: * connection obtained with <code>eglGetDisplay</code>. Initializing
0779: * an already initialized EGL display connection has no effect
0780: * besides returning the version numbers and returing
0781: * <code>true</code>.
0782: *
0783: * <p>No value is returned in <code>major_minor</code> if it is specified as
0784: * <code>null</code>.
0785: *
0786: * <p>Use <code>eglTerminate</code> to release resources associated
0787: * with an EGL display connection.
0788: *
0789: * <h4>Errors</h4>
0790: *
0791: * <p><code>false</code> is returned if <code>eglInitialize</code>
0792: * fails, <code>true</code> otherwise. <code>major_minor</code> is
0793: * not modified when <code>false</code> is returned.
0794: *
0795: * <p><code>EGL_BAD_DISPLAY</code> is generated if
0796: * <code>display</code> is not an EGL display connection.
0797: *
0798: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
0799: * <code>display</code> cannot be initialized.
0800: *
0801: * @param display Specifies the EGL display connection to initialize.
0802: * @param major_minor an <code>int</code> array of length at least
0803: * 2, in which the major and minor version number of the EGL
0804: * implementation will be returned as elements 0 and 1. May be
0805: * <code>null</code>.
0806: *
0807: * @return <code>true</code> if the operation succeeds.
0808: *
0809: * @exception IllegalArgumentException if <code>display</code> is
0810: * <code>null</code>.
0811: * @exception IllegalArgumentException if <code>major_minor</code> is
0812: * non-<code>null</code> but has length less than 2.
0813: */
0814: boolean eglInitialize(EGLDisplay display, int[] major_minor);
0815:
0816: /**
0817: * Terminate an EGL display connection.
0818: *
0819: * <p><code>eglTerminate</code> releases resources associated with
0820: * an EGL display connection. Termination marks all EGL resources
0821: * associated with the EGL display connection for deletion. If
0822: * contexts or surfaces associated with <code>display</code> is
0823: * current to any thread, they are not released until they are no
0824: * longer current as a result of <code>eglMakeCurrent</code>.
0825: *
0826: * <p>Terminating an already terminated EGL display connection has
0827: * no effect other than returning <code>true</code>. A terminated
0828: * display may be re-initialized by calling
0829: * <code>eglInitialize</code> again.
0830: *
0831: * <h4>Errors</h4>
0832: *
0833: * <p><code>false</code> is returned if <code>eglTerminate</code>
0834: * fails, <code>true</code> otherwise.
0835: *
0836: * <p><code>EGL_BAD_DISPLAY</code> is generated if display is not an
0837: * EGL display connection.
0838: *
0839: * @param display Specifies the EGL display connection to terminate.
0840: *
0841: * @exception IllegalArgumentException if <code>display</code> is
0842: * <code>null</code>.
0843: * @return <code>true</code> if the operation succeeds.
0844: */
0845: boolean eglTerminate(EGLDisplay display);
0846:
0847: /**
0848: * Return a string describing an EGL display connection.
0849: *
0850: * <p><code>eglQueryString</code> returns a <code>String</code>
0851: * describing an EGL display connection. <code>name</code> can be
0852: * one of the following:
0853: *
0854: * <ul>
0855: *
0856: * <li><code>EGL_VENDOR</code></li>
0857: *
0858: * <p>Returns the company responsible for this EGL implementation. This
0859: * name does not change from release to release.
0860: *
0861: * <li><code>EGL_VERSION</code></li>
0862: *
0863: * <p>Returns a version or release number. The <code>EGL_VERSION</code>
0864: * string is laid out as follows:
0865: *
0866: * <p><code>major_version.minor_version space vendor_specific_info</code>
0867: *
0868: * <li><code>EGL_EXTENSIONS</code></li>
0869: *
0870: * <p>Returns a space-separated list of supported extensions to EGL.
0871: *
0872: * </ul>
0873: *
0874: * <p>The string data returned from the native EGL implementation is
0875: * converted into UTF8 format and returned as a Java
0876: * <code>String</code>.
0877: *
0878: * <h4>Errors</h4>
0879: *
0880: * <p><code>null</code> is returned on failure.
0881: *
0882: * <p><code>EGL_BAD_DISPLAY</code> is generated if
0883: * <code>display</code> is not an EGL display connection.
0884: *
0885: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
0886: * <code>display</code> has not been initialized.
0887: *
0888: * <p><code>EGL_BAD_PARAMETER</code> is generated if
0889: * <code>name</code> is not an accepted value.
0890: *
0891: * @param display Specifies the EGL display connection.
0892: * @param name Specifies a symbolic constant, one of
0893: * <code>EGL_VENDOR</code>, <code>EGL_VERSION</code>, or
0894: * <code>EGL_EXTENSIONS</code>.
0895: *
0896: * @exception IllegalArgumentException if <code>display</code> is
0897: * <code>null</code>.
0898: * @return A <code>String</code> containing the query result.
0899: */
0900: String eglQueryString(EGLDisplay display, int name);
0901:
0902: /**
0903: * Return a list of all EGL frame buffer configurations for a display.
0904: *
0905: * <p><code>eglGetConfigs</code> returns a list of all EGL frame
0906: * buffer configurations that are available for the specified
0907: * display. The items in the list can be used in any EGL function
0908: * that requires an EGL frame buffer configuration. No more than
0909: * <code>config_size</code> <code>EGLConfig</code>s will be returned
0910: * even if more are available on the specified display.
0911: *
0912: * <p><code>configs</code> does not return values, if it is specified
0913: * as <code>null</code>. This is useful for querying just the number
0914: * of all frame buffer configurations.
0915: *
0916: * <p>Use <code>eglGetConfigAttrib</code> to retrieve individual
0917: * attribute values of a frame buffer configuration.
0918: *
0919: * <h4>Errors</h4>
0920: *
0921: * <p><code>false</code> is returned on failure, <code>true</code>
0922: * otherwise. <code>configs</code> and <code>num_config</code> are
0923: * not modified when <code>false</code> is returned.
0924: *
0925: * <p><code>EGL_BAD_DISPLAY</code> is generated if
0926: * <code>display</code> is not an EGL display connection.
0927: *
0928: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
0929: * <code>display</code> has not been initialized.
0930: *
0931: * <p><code>EGL_BAD_PARAMETER</code> is generated if
0932: * <code>num_config</code> is <code>null</code>.
0933: *
0934: * @param display Specifies the EGL display connection.
0935: * @param configs An array of <code>EGLConfig</code> objects into
0936: * which a list of configs will be stored, or <code>null</code>.
0937: * @param config_size Specifies the size of the list of configs.
0938: * @param num_config An <code>int</code> array, in which the number
0939: * of configs will be returned in element 0.
0940: *
0941: * @return <code>true</code> if the operation succeeds.
0942: *
0943: * @exception IllegalArgumentException if <code>display</code> is
0944: * <code>null</code>.
0945: * @exception IllegalArgumentException if <code>configs</code> is
0946: * non-<code>null</code> and <code>configs.length</code> is smaller
0947: * than <code>config_size</code>.
0948: * @exception IllegalArgumentException if <code>num_config</code> is
0949: * non-<code>null</code> but has length less than 1.
0950: */
0951: boolean eglGetConfigs(EGLDisplay display, EGLConfig[] configs,
0952: int config_size, int[] num_config);
0953:
0954: /**
0955: * Return a list of EGL frame buffer configurations that match
0956: * specified attributes.
0957: *
0958: * <p><code>eglChooseConfig</code> returns a list of all EGL frame
0959: * buffer configurations that match the attributes specified in
0960: * <code>attrib_list</code>. The items in the list can be used in
0961: * any EGL function that requires an EGL frame buffer configuration.
0962: *
0963: * <p><code>configs</code> does not return values, if it is specified
0964: * as <code>null</code>. This is useful for querying just the number
0965: * of matching frame buffer configurations.
0966: *
0967: * <p>All attributes in <code>attrib_list</code>, including boolean
0968: * attributes, are immediately followed by the corresponding desired
0969: * value. The list is terminated with <code>EGL_NONE</code>. If an
0970: * attribute is not specified in <code>attrib_list</code> then the
0971: * default value (see below) is used (and the attribute is said to
0972: * be specified implicitly). For example, if
0973: * <code>EGL_DEPTH_SIZE</code> is not specified then it is assumed
0974: * to be 0. For some attributes, the default is
0975: * <code>EGL_DONT_CARE</code> meaning that any value is OK for this
0976: * attribute, so the attribute will not be checked.
0977: *
0978: * <p> If <code>attrib_list</code> is <code>null</code> or empty
0979: * (first attribute is <code>EGL_NONE</code>), then selection and
0980: * sorting of <code>EGLConfig</code>s is done according to the
0981: * default criteria described below.
0982: *
0983: * <p> Attributes are matched in an attribute-specific manner. Some of
0984: * the attributes, such as <code>EGL_LEVEL</code>, must match the
0985: * specified value exactly. Others, such as,
0986: * <code>EGL_RED_SIZE</code> must meet or exceed the specified
0987: * minimum values. If more than one EGL frame buffer configuration
0988: * is found, then a list of configurations, sorted according to the
0989: * "best" match criteria, is returned. The match criteria for each
0990: * attribute and the exact sorting order is defined below.
0991: *
0992: * <p>The interpretations of the various EGL frame buffer configuration
0993: * attributes are as follows:
0994: *
0995: * <ul>
0996: *
0997: * <li><code>EGL_BUFFER_SIZE</code></li>
0998: *
0999: * <p>Must be followed by a nonnegative integer that indicates the
1000: * desired color buffer size. The smallest color buffer of at least
1001: * the specified size is preferred. The default value is 0.
1002: *
1003: * <li><code>EGL_RED_SIZE</code></li>
1004: *
1005: * <p>Must be followed by a nonnegative minimum size specification. If
1006: * this value is zero, the smallest available red buffer is
1007: * preferred. Otherwise, the largest available red buffer of at
1008: * least the minimum size is preferred. The default value is 0.
1009: *
1010: * <li><code>EGL_GREEN_SIZE</code></li>
1011: *
1012: * <p>Must be followed by a nonnegative minimum size specification. If
1013: * this value is zero, the smallest available green buffer is
1014: * preferred. Otherwise, the largest available green buffer of at
1015: * least the minimum size is preferred. The default value is 0.
1016: *
1017: * <li><code>EGL_BLUE_SIZE</code></li>
1018: *
1019: * <p>Must be followed by a nonnegative minimum size specification. If
1020: * this value is zero, the smallest available blue buffer is
1021: * preferred. Otherwise, the largest available blue buffer of at
1022: * least the minimum size is preferred. The default value is 0.
1023: *
1024: * <li><code>EGL_ALPHA_SIZE</code></li>
1025: *
1026: * <p>Must be followed by a nonnegative minimum size specification. If
1027: * this value is zero, the smallest available alpha buffer is
1028: * preferred. Otherwise, the largest available alpha buffer of at
1029: * least the minimum size is preferred. The default value is 0.
1030: *
1031: * <li><code>EGL_CONFIG_CAVEAT</code></li>
1032: *
1033: * <p>Must be followed by one of <code>EGL_DONT_CARE</code>,
1034: * <code>EGL_NONE</code>, <code>EGL_SLOW_CONFIG</code>,
1035: * <code>EGL_NON_CONFORMANT_CONFIG</code>. If <code>EGL_NONE</code>
1036: * is specified, then only frame buffer configurations with no
1037: * caveats will be considered. If <code>EGL_SLOW_CONFIG</code> is
1038: * specified, then only slow frame buffer configurations will be
1039: * considered. If <code>EGL_NON_CONFORMANT_CONFIG</code> is
1040: * specified, then only non-conformant frame buffer configurations
1041: * will be considered. The default value is
1042: * <code>EGL_DONT_CARE</code>.
1043: *
1044: * <li><code>EGL_CONFIG_ID</code></li>
1045: *
1046: * <p>Must be followed by a valid ID that indicates the desired EGL
1047: * frame buffer configuration. When a <code>EGL_CONFIG_ID</code> is
1048: * specified, all attributes are ignored. The default value is
1049: * <code>EGL_DONT_CARE</code>.
1050: *
1051: * <li><code>EGL_DEPTH_SIZE</code></li>
1052: *
1053: * <p>Must be followed by a nonnegative integer that indicates the
1054: * desired depth buffer size. The smallest available depth buffer of
1055: * at least the minimum size is preferred. If the desired value is
1056: * zero, frame buffer configurations with no depth buffer are
1057: * preferred. The default value is 0.
1058: *
1059: * <li><code>EGL_LEVEL</code></li>
1060: *
1061: * <p>Must be followed by an integer buffer-level specification. This
1062: * specification is honored exactly. Buffer level 0 corresponds to
1063: * the default frame buffer of the display. Buffer level 1 is the
1064: * first overlay frame buffer, level two the second overlay frame
1065: * buffer, and so on. Negative buffer levels correspond to underlay
1066: * frame buffers. The default value is 0.
1067: *
1068: * <li><code>EGL_NATIVE_RENDERABLE</code></li>
1069: *
1070: * <p>Must be followed by <code>EGL_DONT_CARE</code>,
1071: * <code>EGL_TRUE</code>, or <code>EGL_FALSE</code>. If
1072: * <code>EGL_TRUE</code> is specified, then only frame buffer
1073: * configurations that allow native rendering into the surface will
1074: * be considered. The default value is <code>EGL_DONT_CARE</code>.
1075: *
1076: * <li><code>EGL_NATIVE_VISUAL_TYPE</code> (1.0 only)</li>
1077: *
1078: * <p>Must be followed by a platform dependent value or
1079: * <code>EGL_DONT_CARE</code>. The default value is
1080: * <code>EGL_DONT_CARE</code>.
1081: *
1082: * <li><code>EGL_SAMPLE_BUFFERS</code></li>
1083: *
1084: * <p>Must be followed by the minimum acceptable number of multisample
1085: * buffers. Configurations with the smallest number of multisample
1086: * buffers that meet or exceed this minimum number are
1087: * preferred. Currently operation with more than one multisample
1088: * buffer is undefined, so only values of zero or one will produce a
1089: * match. The default value is 0.
1090: *
1091: * <li><code>EGL_SAMPLES</code></li>
1092: *
1093: * <p>Must be followed by the minimum number of samples required in
1094: * multisample buffers. Configurations with the smallest number of
1095: * samples that meet or exceed the specified minimum number are
1096: * preferred. Note that it is possible for color samples in the
1097: * multisample buffer to have fewer bits than colors in the main
1098: * color buffers. However, multisampled colors maintain at least as
1099: * much color resolution in aggregate as the main color buffers.
1100: *
1101: * <li><code>EGL_STENCIL_SIZE</code></li>
1102: *
1103: * <p>Must be followed by a nonnegative integer that indicates the
1104: * desired number of stencil bitplanes. The smallest stencil buffer
1105: * of at least the specified size is preferred. If the desired value
1106: * is zero, frame buffer configurations with no stencil buffer are
1107: * preferred. The default value is 0.
1108: *
1109: * <li><code>EGL_SURFACE_TYPE</code></li>
1110: *
1111: * <p>Must be followed by a mask indicating which EGL surface types
1112: * the frame buffer configuration must support. Valid bits are
1113: * <code>EGL_WINDOW_BIT</code>, <code>EGL_PBUFFER_BIT</code>, and
1114: * <code>EGL_PIXMAP_BIT</code>. For example, if <code>mask</code> is
1115: * set to <code>EGL_WINDOW_BIT | EGL_PIXMAP_BIT</code>,
1116: * only frame buffer configurations that support both windows and
1117: * pixmaps will be considered. The default value is
1118: * <code>EGL_WINDOW_BIT</code>.
1119: *
1120: * <li><code>EGL_TRANSPARENT_TYPE</code></li>
1121: *
1122: * <p>Must be followed by one of <code>EGL_NONE</code> or
1123: * <code>EGL_TRANSPARENT_RGB</code>. If <code>EGL_NONE</code> is
1124: * specified, then only opaque frame buffer configurations will be
1125: * considered. If <code>EGL_TRANSPARENT_RGB</code> is specified,
1126: * then only transparent frame buffer configurations will be
1127: * considered. The default value is <code>EGL_NONE</code>.
1128: *
1129: * <li><code>EGL_TRANSPARENT_RED_VALUE</code></li>
1130: *
1131: * <p>Must be followed by an integer value indicating the transparent
1132: * red value. The value must be between 0 and the maximum color
1133: * buffer value for red. Only frame buffer configurations that use
1134: * the specified transparent red value will be considered. The
1135: * default value is <code>EGL_DONT_CARE</code>.
1136: *
1137: * <p>This attribute is ignored unless
1138: * <code>EGL_TRANSPARENT_TYPE</code> is included in
1139: * <code>attrib_list</code> and specified as
1140: * <code>EGL_TRANSPARENT_RGB</code>.
1141: *
1142: * <li><code>EGL_TRANSPARENT_GREEN_VALUE</code></li>
1143: *
1144: * <p>Must be followed by an integer value indicating the transparent
1145: * green value. The value must be between 0 and the maximum color
1146: * buffer value for red. Only frame buffer configurations that use
1147: * the specified transparent green value will be considered. The
1148: * default value is <code>EGL_DONT_CARE</code>.
1149: *
1150: * <p>This attribute is ignored unless
1151: * <code>EGL_TRANSPARENT_TYPE</code> is included in
1152: * <code>attrib_list</code> and specified as
1153: * <code>EGL_TRANSPARENT_RGB</code>.
1154: *
1155: * <li><code>EGL_TRANSPARENT_BLUE_VALUE</code></li>
1156: *
1157: * <p>Must be followed by an integer value indicating the transparent
1158: * blue value. The value must be between 0 and the maximum color
1159: * buffer value for red. Only frame buffer configurations that use
1160: * the specified transparent blue value will be considered. The
1161: * default value is <code>EGL_DONT_CARE</code>.
1162: *
1163: * <p>This attribute is ignored unless
1164: * <code>EGL_TRANSPARENT_TYPE</code> is included in
1165: * <code>attrib_list</code> and specified as
1166: * <code>EGL_TRANSPARENT_RGB</code>.
1167: *
1168: * <li><code>EGL_BIND_TO_TEXTURE_RGB</code> (1.1 only)</li>
1169: *
1170: * <p>Must be followed by <code>EGL_DONT_CARE</code>,
1171: * <code>EGL_TRUE</code>, or <code>EGL_FALSE</code>. If
1172: * <code>EGL_TRUE</code> is specified, then only frame buffer
1173: * configurations that support binding of color buffers to an RGB
1174: * texture will be considered. Currently only frame buffer
1175: * configurations that support pbuffers allow this. The default
1176: * value is <code>EGL_DONT_CARE</code>.
1177: *
1178: * <li><code>EGL_BIND_TO_TEXTURE_RGBA</code> (1.1 only)></li>
1179: *
1180: * <p>Must be followed by <code>EGL_DONT_CARE</code>,
1181: * <code>EGL_TRUE</code>, or <code>EGL_FALSE</code>. If
1182: * <code>EGL_TRUE</code> is specified, then only frame buffer
1183: * configurations that support binding of color buffers to an RGBA
1184: * texture will be considered. Currently only frame buffer
1185: * configurations that support pbuffers allow this. The default
1186: * value is <code>EGL_DONT_CARE</code>.
1187: *
1188: * <li><code>EGL_MAX_SWAP_INTERVAL</code> (1.1 only)</li>
1189: *
1190: * <p>Must be followed by a integer that indicates the maximum value
1191: * that can be passed to <code>eglSwapInterval</code>. The default
1192: * value is <code>EGL_DONT_CARE</code>.
1193: *
1194: * <li><code>EGL_MIN_SWAP_INTERVAL</code> (1.1 only)</li>
1195: *
1196: * <p>Must be followed by a integer that indicates the minimum value
1197: * that can be passed to <code>eglSwapInterval</code>. The default
1198: * value is <code>EGL_DONT_CARE</code>.
1199: *
1200: * </ul>
1201: *
1202: * <p>When more than one EGL frame buffer configuration matches the
1203: * specified attributes, a list of matching configurations is
1204: * returned. The list is sorted according to the following
1205: * precedence rules, which are applied in ascending order (i.e.,
1206: * configurations that are considered equal by a lower numbered rule
1207: * are sorted by the higher numbered rule):
1208: *
1209: * <ol>
1210: *
1211: * <li>By <code>EGL_CONFIG_CAVEAT</code>, where the precedence is
1212: * <code>EGL_NONE</code>, <code>EGL_SLOW_CONFIG</code>, and
1213: * <code>EGL_NON_CONFORMANT_CONFIG</code>.</li>
1214: *
1215: * <li>Larger total number of color components
1216: * (<code>EGL_RED_SIZE</code>, <code>EGL_GREEN_SIZE</code>,
1217: * <code>EGL_BLUE_SIZE</code>, and <code>EGL_ALPHA_SIZE</code>) that
1218: * have higher number of bits. If the requested number of bits in
1219: * <code>attrib_list</code> is zero or <code>EGL_DONT_CARE</code>
1220: * for a particular color component, then the number of bits for
1221: * that component is not considered.</li>
1222: *
1223: * <li>Smaller <code>EGL_BUFFER_SIZE</code>.</li>
1224: *
1225: * <li>Smaller <code>EGL_SAMPLE_BUFFERS</code>.</li>
1226: *
1227: * <li>Smaller <code>EGL_SAMPLES</code>.</li>
1228: *
1229: * <li>Smaller <code>EGL_DEPTH_SIZE</code>.</li>
1230: *
1231: * <li>Smaller <code>EGL_STENCIL_SIZE</code>.</li>
1232: *
1233: * <li>By <code>EGL_NATIVE_VISUAL_TYPE</code>, where the precedence
1234: * order is platform dependent.</li>
1235: *
1236: * <li>Smaller <code>EGL_CONFIG_ID</code>.</li>
1237: *
1238: * </ol>
1239: *
1240: * <p>(1.1) <code>EGLConfigs</code> are not sorted with respect to the
1241: * parameters <code>EGL_BIND_TO_TEXTURE_RGB</code>,
1242: * <code>EGL_BIND_TO_TEXTURE_RGBA</code>, <code>EGL_LEVEL</code>,
1243: * <code>EGL_NATIVE_RENDERABLE</code>,
1244: * <code>EGL_MAX_SWAP_INTERVAL</code>,
1245: * <code>EGL_MIN_SWAP_INTERVAL</code>,
1246: * <code>EGL_SURFACE_TYPE</code>, <code>EGL_TRANSPARENT_TYPE</code>,
1247: * <code>EGL_TRANSPARENT_RED_VALUE</code>,
1248: * <code>EGL_TRANSPARENT_GREEN_VALUE</code>, and
1249: * <code>EGL_TRANSPARENT_BLUE_VALUE</code>.
1250: *
1251: * <h4>Examples</h4>
1252: *
1253: * <p>The following example specifies a frame buffer configuration in
1254: * the normal frame buffer (not an overlay or underlay). The
1255: * returned frame buffer configuration supports at least 4 bits each
1256: * of red, green and blue and possible no alpha bits. The code shown
1257: * in the example may or may not have a depth buffer, or a stencil
1258: * buffer.
1259: *
1260: * <pre>
1261: * int attrib_list[] = {
1262: * EGL10.EGL_RED_SIZE, 4,
1263: * EGL10.EGL_GREEN_SIZE, 4,
1264: * EGL10.EGL_BLUE_SIZE, 4,
1265: * EGL10.EGL_NONE
1266: * };
1267: * </pre>
1268: *
1269: * <h4>Notes</h4>
1270: *
1271: * <p><code>eglGetConfigs</code> and <code>eglGetConfigAttrib</code> can be
1272: * used to implement selection algorithms other than the generic one
1273: * implemented by <code>eglChooseConfig</code>. Call
1274: * <code>eglGetConfigs</code> to retrieve all the frame buffer
1275: * configurations, or alternatively, all the frame buffer configurations
1276: * with a particular set of attributes. Next call
1277: * <code>eglGetConfigAttrib</code> to retrieve additional attributes for
1278: * the frame buffer configurations and then select between them.
1279: *
1280: * <p>EGL implementors are strongly discouraged, but not proscribed, from
1281: * changing the selection algorithm used by
1282: * <code>eglChooseConfig</code>. Therefore, selections may change from
1283: * release to release of the client-side library.
1284: *
1285: * <h4>Errors</h4>
1286: *
1287: * <p><code>false</code> is returned on failure, <code>true</code>
1288: * otherwise. <code>configs</code> and <code>num_config</code> are
1289: * not modified when <code>false</code> is returned.
1290: *
1291: * <p><code>EGL_BAD_DISPLAY</code> is generated if
1292: * <code>display</code> is not an EGL display connection.
1293: *
1294: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1295: * <code>attribute_list</code> contains an invalid frame buffer
1296: * configuration attribute or an attribute value that is
1297: * unrecognized or out of range.
1298: *
1299: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1300: * <code>display</code> has not been initialized.
1301: *
1302: * <p><code>EGL_BAD_PARAMETER</code> is generated if
1303: * <code>num_config</code> is <code>null</code>.
1304: *
1305: * @param display Specifies the EGL display connection.
1306: * @param attrib_list Specifies attributes required to match by configs.
1307: * @param configs Returns an array of frame buffer configurations.
1308: * @param config_size Specifies the size of the array of frame
1309: * buffer configurations.
1310: * @param num_config An <code>int</code> array in which the number of frame
1311: * buffer configurations will be returned in element 0.
1312: * @return <code>true</code> if the operation succeeds.
1313: *
1314: * @exception IllegalArgumentException if <code>display</code> is
1315: * <code>null</code>.
1316: * @exception IllegalArgumentException if <code>attrib_list</code> is
1317: * non-<code>null</code> but is not terminated with
1318: * <code>EGL_NONE</code>.
1319: * @exception IllegalArgumentException if <code>configs</code> is
1320: * non-<code>null</code> and <code>configs.length</code> is smaller
1321: * than <code>config_size</code>.
1322: * @exception IllegalArgumentException if <code>num_config</code> is
1323: * non-<code>null</code> but has length less than 1.
1324: */
1325: boolean eglChooseConfig(EGLDisplay display, int[] attrib_list,
1326: EGLConfig[] configs, int config_size, int[] num_config);
1327:
1328: /**
1329: * Return information about an EGL frame buffer configuration.
1330: *
1331: * <p><code>eglGetConfigAttrib</code> returns in <code>value[0]</code> the
1332: * value of <code>attribute</code> for
1333: * <code>config</code>. <code>attribute</code> can be one of the
1334: * following:
1335: *
1336: * <ul>
1337: *
1338: * <li><code>EGL_BUFFER_SIZE</code></li>
1339: *
1340: * <p>Returns the depth of the color buffer. It is the sum of
1341: * <code>EGL_RED_SIZE</code>, <code>EGL_GREEN_SIZE</code>,
1342: * <code>EGL_BLUE_SIZE</code>, and <code>EGL_ALPHA_SIZE</code>.
1343: *
1344: * <li><code>EGL_RED_SIZE</code></li>
1345: *
1346: * <p>Returns the number of bits of red stored in the color buffer.
1347: *
1348: * <li><code>EGL_GREEN_SIZE</code></li>
1349: *
1350: * <p>Returns the number of bits of green stored in the color buffer.
1351: *
1352: * <li><code>EGL_BLUE_SIZE</code></li>
1353: *
1354: * <p>Returns the number of bits of blue stored in the color buffer.
1355: *
1356: * <li><code>EGL_ALPHA_SIZE</code></li>
1357: *
1358: * <p>Returns the number of bits of alpha stored in the color buffer.
1359: *
1360: * <li><code>EGL_CONFIG_CAVEAT</code></li>
1361: *
1362: * <p>Returns the caveats for the frame buffer configuration. Possible
1363: * caveat values are <code>EGL_NONE</code>,
1364: * <code>EGL_SLOW_CONFIG</code>, and
1365: * <code>EGL_NON_CONFORMANT</code>.
1366: *
1367: * <li><code>EGL_CONFIG_ID</code></li>
1368: *
1369: * <p>Returns the ID of the frame buffer configuration.
1370: *
1371: * <li><code>EGL_DEPTH_SIZE</code></li>
1372: *
1373: * <p>Returns the number of bits in the depth buffer.
1374: *
1375: * <li><code>EGL_LEVEL</code></li>
1376: *
1377: * <p>Returns the frame buffer level. Level zero is the default frame
1378: * buffer. Positive levels correspond to frame buffers that overlay
1379: * the default buffer and negative levels correspond to frame
1380: * buffers that underlay the default buffer.
1381: *
1382: * <li><code>EGL_MAX_PBUFFER_WIDTH</code></li>
1383: *
1384: * <p>Returns the maximum width of a pixel buffer surface in pixels.
1385: *
1386: * <li><code>EGL_MAX_PBUFFER_HEIGHT</code></li>
1387: *
1388: * <p>Returns the maximum height of a pixel buffer surface in pixels.
1389: *
1390: * <li><code>EGL_MAX_PBUFFER_PIXELS</code></li>
1391: *
1392: * <p>Returns the maximum size of a pixel buffer surface in pixels.
1393: *
1394: * <li><code>EGL_NATIVE_RENDERABLE</code></li>
1395: *
1396: * <p>Returns <code>EGL_TRUE</code> if native rendering APIs can render
1397: * into the surface, <code>EGL_FALSE</code> otherwise.
1398: *
1399: * <li><code>EGL_NATIVE_VISUAL_ID</code></li>
1400: *
1401: * <p>Returns the ID of the associated native visual.
1402: *
1403: * <li><code>EGL_NATIVE_VISUAL_TYPE</code></li>
1404: *
1405: * <p>Returns the type of the associated native visual.
1406: *
1407: * <li><code>EGL_PRESERVED_RESOURCES</code> (1.0 only)</li>
1408: *
1409: * Returns <code>EGL_TRUE</code> if resources are preserved across
1410: * power management events, <code>EGL_FALSE</code> otherwise.
1411: *
1412: * <li><code>EGL_SAMPLE_BUFFERS</code></li>
1413: *
1414: * <p>Returns the number of multisample buffers.
1415: *
1416: * <li><code>EGL_SAMPLES</code></li>
1417: *
1418: * <p>Returns the number of samples per pixel.
1419: *
1420: * <li><code>EGL_STENCIL_SIZE</code></li>
1421: *
1422: * <p>Returns the number of bits in the stencil buffer.
1423: *
1424: * <li><code>EGL_SURFACE_TYPE</code></li>
1425: *
1426: * <p>Returns the types of supported EGL surfaces.
1427: *
1428: * <li><code>EGL_TRANSPARENT_TYPE</code></li>
1429: *
1430: * <p>Returns the type of supported transparency. Possible transparency
1431: * values are: <code>EGL_NONE</code>, and
1432: * <code>EGL_TRANSPARENT_RGB</code>.
1433: *
1434: * <li><code>EGL_TRANSPARENT_RED_VALUE</code></li>
1435: *
1436: * <p>Returns the transparent red value.
1437: *
1438: * <li><code>EGL_TRANSPARENT_GREEN_VALUE</code></li>
1439: *
1440: * <p>Returns the transparent green value.
1441: *
1442: * <li><code>EGL_TRANSPARENT_BLUE_VALUE</code></li>
1443: *
1444: * <p>Returns the transparent blue value.
1445: *
1446: * <li><code>EGL_BIND_TO_TEXTURE_RGB</code> (1.1 only)</li>
1447: *
1448: * <p>Returns <code>EGL_TRUE</code> if color buffers can be bound to an
1449: * RGB texture, <code>EGL_FALSE</code> otherwise.
1450: *
1451: * <li><code>EGL_BIND_TO_TEXTURE_RGBA</code> (1.1 only)</li>
1452: *
1453: * <p>Returns <code>EGL_TRUE</code> if color buffers can be bound to an
1454: * RGBA texture, <code>EGL_FALSE</code> otherwise.
1455: *
1456: * <li><code>EGL_MAX_SWAP_INTERVAL</code> (1.1 only)</li>
1457: *
1458: * <p>Returns the maximum value that can be passed to
1459: * <code>eglSwapInterval</code>.
1460: *
1461: * <li><code>EGL_MIN_SWAP_INTERVAL</code> (1.1 only)</li>
1462: *
1463: * <p>Returns the minimum value that can be passed to
1464: * <code>eglSwapInterval</code>.
1465: *
1466: * </ul>
1467: *
1468: * <h4>Errors</h4>
1469: *
1470: * <p><code>false</code> is returned on failure, <code>true</code>
1471: * otherwise. <code>value</code> is not modified when
1472: * <code>false</code> is returned.
1473: *
1474: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1475: * is not an EGL display connection.
1476: *
1477: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1478: * <code>display</code> has not been initialized.
1479: *
1480: * <p><code>EGL_BAD_CONFIG</code> is generated if <code>config</code>
1481: * is not an EGL frame buffer configuration.
1482: *
1483: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1484: * <code>attribute</code> is not a valid frame buffer configuration
1485: * attribute.
1486: *
1487: * @param display Specifies the EGL display connection.
1488: * @param config Specifies the EGL frame buffer configuration to be queried.
1489: * @param attribute Specifies the EGL rendering context attribute to
1490: * be returned.
1491: * @param value An <code>int</code> array of length at least 1 in
1492: * which the requested value will be returned as element 0.
1493: *
1494: * @exception IllegalArgumentException if <code>display</code> is
1495: * <code>null</code>.
1496: * @exception IllegalArgumentException if <code>config</code> is
1497: * <code>null</code>.
1498: * @exception IllegalArgumentException if <code>value</code> is
1499: * <code>null</code> or has length less than 1.
1500: *
1501: * @return <code>true</code> if the query succeeds.
1502: */
1503: boolean eglGetConfigAttrib(EGLDisplay display, EGLConfig config,
1504: int attribute, int[] value);
1505:
1506: /**
1507: * Create a new EGL window surface.
1508: *
1509: * <p><code>eglCreateWindowSurface</code> creates an EGL window surface
1510: * and returns its handle. If <code>eglCreateWindowSurface</code>
1511: * fails to create a window surface, <code>EGL_NO_SURFACE</code> is
1512: * returned.
1513: *
1514: * <p>Any EGL rendering context that was created with respect to
1515: * <code>config</code> can be used to render into the surface. Use
1516: * <code>eglMakeCurrent</code> to attach an EGL rendering context to
1517: * the surface.
1518: *
1519: * <p>Use <code>eglQuerySurface</code> to retrieve the ID of
1520: * <code>config</code>.
1521: *
1522: * <p>Use <code>eglDestroySurface</code> to destroy the surface.
1523: *
1524: * <h4>Notes</h4>
1525: *
1526: * <p>On JME CLDC/MIDP platforms, <code>native_window</code> must be
1527: * an instance of <code>javax.microedition.lcdui.Graphics</code>
1528: * object created directly from an instance of
1529: * <code>GameCanvas</code> or from the argument supplied to the
1530: * <code>Canvas.paint</code> method. <!-- <code>EGLCanvas</code> -->
1531: *
1532: * <!--
1533: * <p>On JME Personal Basis Profile platforms,
1534: * <code>native_window</code> must be an instance of
1535: * <code>java.awt.Container</code>.
1536:
1537: * <p>On JME Personal Profile platforms,
1538: * <code>native_window</code> must be an instance of
1539: * <code>java.awt.Canvas</code>.
1540: * -->
1541: *
1542: * <h4>Errors</h4>
1543: *
1544: * <p><code>EGL_NO_SURFACE</code> is returned if creation of the
1545: * context fails.
1546: *
1547: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1548: * is not an EGL display connection.
1549: *
1550: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1551: * <code>display</code> has not been initialized.
1552: *
1553: * <p><code>EGL_BAD_CONFIG</code> is generated if <code>config</code>
1554: * is not an EGL frame buffer configuration.
1555: *
1556: * <p><code>EGL_BAD_NATIVE_WINDOW</code> may be generated if
1557: * <code>native_window</code> is not a valid native window.
1558: *
1559: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1560: * <code>attrib_list</code> contains an invalid window attribute or
1561: * if an attribute value is not recognized or is out of range.
1562: *
1563: * <p><code>EGL_BAD_ALLOC</code> is generated if there are not enough
1564: * resources to allocate the new surface.
1565: *
1566: * <p><code>EGL_BAD_MATCH</code> is generated if the attributes of
1567: * <code>native_window</code> do not correspond to
1568: * <code>config</code> or if <code>config</code> does not support
1569: * rendering to windows (the <code>EGL_SURFACE_TYPE</code> attribute
1570: * does not contain <code>EGL_WINDOW_BIT</code>).
1571: *
1572: * @param display Specifies the EGL display connection.
1573: * @param config Specifies the EGL frame buffer configuration that
1574: * defines the frame buffer resource available to the surface.
1575: * @param native_window Specifies the native window.
1576: * @param attrib_list Specifies window surface attributes. Must be
1577: * <code>null</code> or empty (first attribute is <code>EGL_NONE</code>).
1578: *
1579: * @return an <code>EGLSurface</code> for rendering to the window.
1580: *
1581: * @exception IllegalArgumentException if <code>display</code> is
1582: * <code>null</code>.
1583: * @exception IllegalArgumentException if <code>config</code> is
1584: * <code>null</code>.
1585: * @exception IllegalArgumentException if <code>native_window</code>
1586: * is <code>null</code> or is not of a suitable type for the
1587: * underlying platform (e.g., not a properly-created
1588: * <code>javax.microedition.lcdui.Graphics</code> instance for
1589: * CLDC/MIDP).
1590: * @exception IllegalArgumentException if <code>attrib_list</code>
1591: * is non-<code>null</code> but is not terminated with
1592: * <code>EGL_NONE</code>.
1593: */
1594: EGLSurface eglCreateWindowSurface(EGLDisplay display,
1595: EGLConfig config, Object native_window, int[] attrib_list);
1596:
1597: /**
1598: * Create a new EGL pixmap surface.
1599: *
1600: * <p><code>eglCreatePixmapSurface</code> creates an off-screen EGL
1601: * pixmap surface and returns its handle. If
1602: * <code>eglCreatePixmapSurface</code> fails to create a pixmap
1603: * surface, <code>EGL_NO_SURFACE</code> is returned.
1604: *
1605: * <p>Any EGL rendering context that was created with respect to
1606: * <code>config</code> can be used to render into the surface. Use
1607: * <code>eglMakeCurrent</code> to attach an EGL rendering context to
1608: * the surface.
1609: *
1610: * <p>Use <code>eglQuerySurface</code> to retrieve the ID of
1611: * <code>config</code>.
1612: *
1613: * <p>Use <code>eglDestroySurface</code> to destroy the surface.
1614: *
1615: * <h4>Notes</h4>
1616: *
1617: * <p>On JME CLDC/MIDP platforms, <code>native_pixmap</code> must be
1618: * an instance of <code>javax.microedition.lcdui.Graphics</code>
1619: * that was created directly from a mutable instance of
1620: * <code>javax.microedition.lcdui.Image</code>.
1621: *
1622: * <!--
1623: * <p>On JME Personal Basis Profile and Personal Profile platforms,
1624: * <code>native_pixmap</code> must be an instance of
1625: * <code>java.awt.Graphics</code> that was created using the
1626: * <code>BufferedImage.getGraphics</code> or
1627: * <code>createGraphics</code> methods.
1628: * -->
1629: *
1630: * <h4>Errors</h4>
1631: *
1632: * <p><code>EGL_NO_SURFACE</code> is returned if creation of the
1633: * context fails.
1634: *
1635: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1636: * is not an EGL display connection.
1637: *
1638: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1639: * <code>display</code> has not been initialized.
1640: *
1641: * <p><code>EGL_BAD_CONFIG</code> is generated if <code>config</code>
1642: * is not an EGL config.
1643: *
1644: * <p><code>EGL_BAD_NATIVE_PIXMAP</code> may be generated if
1645: * <code>native_pixmap</code> is not a valid native pixmap.
1646: *
1647: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1648: * <code>attrib_list</code> contains an invalid pixmap attribute or
1649: * if an attribute value is not recognized or out of range.
1650: *
1651: * <p><code>EGL_BAD_ALLOC</code> is generated if there are not enough
1652: * resources to allocate the new surface.
1653: *
1654: * <p><code>EGL_BAD_MATCH</code> is generated if the attributes of
1655: * <code>native_pixmap</code> do not correspond to
1656: * <code>config</code> or if <code>config</code> does not support
1657: * rendering to pixmaps (the <code>EGL_SURFACE_TYPE</code> attribute
1658: * does not contain <code>EGL_PIXMAP_BIT</code>).
1659: *
1660: * @param display Specifies the EGL display connection.
1661: * @param config Specifies the EGL frame buffer configuration that
1662: * defines the frame buffer resource available to the surface.
1663: * @param native_pixmap Specifies the native pixmap.
1664: * @param attrib_list Specifies pixmap surface attributes. Must be
1665: * <code>null</code> or empty (first attribute is <code>EGL_NONE</code>).
1666: *
1667: * @return An <code>EGLSurface</code> for offscreen rendering.
1668: *
1669: * @exception IllegalArgumentException if <code>display</code> is
1670: * <code>null</code>.
1671: * @exception IllegalArgumentException if <code>config</code> is
1672: * <code>null</code>
1673: * @exception IllegalArgumentException if <code>native_pixmap</code>
1674: * is <code>null</code> or is not of a suitable type for the
1675: * underlying platform (e.g., not a mutable <code>Image</code> for
1676: * CLDC/MIDP).
1677: * @exception IllegalArgumentException if <code>attrib_list</code>
1678: * is non-<code>null</code> but is not terminated with
1679: * <code>EGL_NONE</code>.
1680: */
1681: EGLSurface eglCreatePixmapSurface(EGLDisplay display,
1682: EGLConfig config, Object native_pixmap, int[] attrib_list);
1683:
1684: /**
1685: * Create a new EGL pixel buffer surface.
1686: *
1687: * <p><code>eglCreatePbufferSurface</code> creates an off-screen pixel
1688: * buffer surface and returns its handle. If
1689: * <code>eglCreatePbufferSurface</code> fails to create a pixel
1690: * buffer surface, <code>EGL_NO_SURFACE</code> is returned.
1691: *
1692: * <p>Any EGL rendering context that was created with respect to
1693: * <code>config</code> can be used to render into the surface. Use
1694: * <code>eglMakeCurrent</code> to attach an EGL rendering context to
1695: * the surface.
1696: *
1697: * <p>Use <code>eglQuerySurface</code> to retrieve the dimensions of
1698: * the allocated pixel buffer surface or the ID of
1699: * <code>config</code>.
1700: *
1701: * <p>Use <code>eglDestroySurface</code> to destroy the surface.
1702: *
1703: * <p>The pixel buffer surface attributes are specified in
1704: * <code>attrib_list</code> as a list of attribute value pairs,
1705: * terminated with <code>EGL_NONE</code>. A <code>null</code> value
1706: * for <code>attrib_list</code> is treated as an empty list. The
1707: * accepted attributes for an EGL pixel buffer surface are:
1708: *
1709: * <ul>
1710: *
1711: * <li><code>EGL_WIDTH</code></li>
1712: *
1713: * <p>Specifies the requested width of the pixel buffer surface. The
1714: * default value is 0.
1715: *
1716: * <li><code>EGL_HEIGHT</code></li>
1717: *
1718: * <p>Specifies the requests height of the pixel buffer surface. The
1719: * default value is 0.
1720: *
1721: * <li><code>EGL_LARGEST_PBUFFER</code></li>
1722: *
1723: * <p>Requests the largest available pixel buffer surface when the
1724: * allocation would otherwise fail. Use <code>eglQuerySurface</code>
1725: * to retrieve the dimensions of the allocated pixel buffer. The
1726: * default value is <code>EGL_FALSE</code>.
1727: *
1728: * <li><code>EGL_TEXTURE_FORMAT</code> (1.1 only)</li>
1729: *
1730: * <p>Specifies the format of the texture that will be created when
1731: * a pbuffer is bound to a texture map. Possible values are
1732: * <code>EGL_NO_TEXTURE</code>, <code>EGL_TEXTURE_RGB</code>, and
1733: * <code>EGL_TEXTURE_RGBA</code>. The default value is
1734: * <code>EGL_NO_TEXTURE</code>.
1735: *
1736: * <li><code>EGL_TEXTURE_TARGET</code> (1.1 only)</li>
1737: *
1738: * <p>Specifies the target for the texture that will be created when
1739: * the pbuffer is created with a texture format of
1740: * <code>EGL_TEXTURE_RGB</code> or
1741: * <code>EGL_TEXTURE_RGBA</code>. Possible values are
1742: * <code>EGL_NO_TEXTURE</code>, or <code>EGL_TEXTURE_2D</code>. The
1743: * default value is <code>EGL_NO_TEXTURE</code>.
1744: *
1745: * <li><code>EGL_MIPMAP_TEXTURE</code> (1.1 only)</li>
1746: *
1747: * <p>Specifies whether storage for mipmaps should be allocated. Space
1748: * for mipmaps will be set aside if the attribute value is
1749: * <code>EGL_TRUE</code> and <code>EGL_TEXTURE_FORMAT</code> is not
1750: * <code>EGL_NO_TEXTURE</code>. The default value is
1751: * <code>EGL_FALSE</code>.
1752: *
1753: * </ul>
1754: *
1755: * <h4>1.1 Notes</h4>
1756: *
1757: * <p>If the value of config attribute <code>EGL_TEXTURE_FORMAT</code>
1758: * is not <code>EGL_NO_TEXTURE</code>, then the pbuffer width and
1759: * height specify the size of the level zero texture image
1760: *
1761: * <p>If <code>EGL_LARGEST_PBUFFER</code> is specified and if the
1762: * pbuffer will be used as a texture (i.e. the value of
1763: * <code>EGL_TEXTURE_TARGET</code> is <code>EGL_TEXTURE_2D</code>,
1764: * and the value of EGL_TEXTURE <code>FORMAT</code> is
1765: * <code>EGL_TEXTURE_RGB</code> or <code>EGL_TEXTURE_RGBA</code>),
1766: * then the aspect ratio will be preserved and the new width and
1767: * height will be valid sizes for the texture target (e.g. if the
1768: * underlying OpenGL ES implementation does not support
1769: * non-power-of-two textures, both the width and height will be a
1770: * power of 2).
1771: *
1772: * <p>The contents of the depth and stencil buffers may not be
1773: * preserved when rendering a texture to the pbuffer and switching
1774: * which image of the texture is rendered to (e.g., switching from
1775: * rendering one mipmap level to rendering another).
1776: *
1777: * <h4>Errors</h4>
1778: *
1779: * <p><code>EGL_NO_SURFACE</code> is returned if creation of the
1780: * context fails.
1781: *
1782: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1783: * is not an EGL display connection.
1784: *
1785: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1786: * <code>display</code> has not been initialized.
1787: *
1788: * <p><code>EGL_BAD_CONFIG</code> is generated if <code>config</code>
1789: * is not an EGL frame buffer configuration.
1790: *
1791: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1792: * <code>attrib_list</code> contains an invalid pixel buffer
1793: * attribute or if an attribute value is not recognized or out of
1794: * range.
1795: *
1796: * <p><code>EGL_BAD_ALLOC</code> is generated if there are not enough
1797: * resources to allocate the new surface.
1798: *
1799: * <p><code>EGL_BAD_MATCH</code> is generated if <code>config</code>
1800: * does not support rendering to pixel buffers (the
1801: * <code>EGL_SURFACE_TYPE</code> attribute does not contain
1802: * <code>EGL_PBUFFER_BIT</code>).
1803: *
1804: * <p>(1.1 only) <code>EGL_BAD_VALUE</code> is generated if the
1805: * <code>EGL_TEXTURE_FORMAT</code> attribute is not
1806: * <code>EGL_NO_TEXTURE</code>, and <code>EGL_WIDTH</code> and/or
1807: * <code>EGL_HEIGHT</code> specify an invalid size (e.g., the
1808: * texture size is not a power of 2, and the underlying OpenGL ES
1809: * implementation does not support non-power-of-two textures).
1810: *
1811: * <p>(1.1 only) <code>EGL_BAD_VALUE</code> can also be generated if
1812: * The <code>EGL_TEXTURE_FORMAT</code> attribute is
1813: * <code>EGL_NO_TEXTURE</code>, and <code>EGL_TEXTURE_TARGET</code>
1814: * is something other than <code>EGL_NO_TEXTURE</code>; or,
1815: * <code>EGL_TEXTURE_FORMAT</code> is something other than
1816: * <code>EGL_NO_TEXTURE</code>, and <code>EGL_TEXTURE_TARGET</code>
1817: * is <code>EGL_NO_TEXTURE</code>.
1818: *
1819: * @param display Specifies the EGL display connection.
1820: * @param config Specifies the EGL frame buffer configuration that
1821: * defines the frame buffer resource available to the surface.
1822: * @param attrib_list Specifies the pixel buffer surface
1823: * attributes. May be <code>null</code> or empty (first attribute is
1824: * <code>EGL_NONE</code>).
1825: *
1826: * @return An <code>EGLSurface</code> for offscreen rendering.
1827: *
1828: * @exception IllegalArgumentException if <code>display</code> is
1829: * <code>null</code>.
1830: * @exception IllegalArgumentException if <code>config</code> is
1831: * <code>null</code>.
1832: * @exception IllegalArgumentException if <code>attrib_list</code>
1833: * is non-<code>null</code> but is not terminated with
1834: * <code>EGL_NONE</code>.
1835: */
1836: EGLSurface eglCreatePbufferSurface(EGLDisplay display,
1837: EGLConfig config, int[] attrib_list);
1838:
1839: /**
1840: * Destroy an EGL surface.
1841: *
1842: * <p>If the EGL surface <code>surface</code> is not current to any
1843: * thread, <code>eglDestroySurface</code> destroys it
1844: * immediately. Otherwise, <code>surface</code> is destroyed when it
1845: * becomes not current to any thread.
1846: *
1847: * <p>(1.1) In OpenGL ES 1.1, resources associated with a pbuffer surface
1848: * are not released until all color buffers of that pbuffer bound to
1849: * a texture object have been released.
1850: *
1851: * <h4>Errors</h4>
1852: *
1853: * <p><code>false</code> is returned if destruction of the surface
1854: * fails, <code>true</code> otherwise.
1855: *
1856: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1857: * is not an EGL display connection.
1858: *
1859: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1860: * <code>display</code> has not been initialized.
1861: *
1862: * <p><code>EGL_BAD_SURFACE</code> is generated if <code>surface</code>
1863: * is not an EGL surface.
1864: *
1865: * @param display Specifies the EGL display connection.
1866: * @param surface Specifies the EGL surface to be destroyed.
1867: *
1868: * @exception IllegalArgumentException if <code>display</code> is
1869: * <code>null</code>.
1870: * @exception IllegalArgumentException if <code>surface</code> is
1871: * <code>null</code>.
1872: *
1873: * @return <code>true</code> if the operation succeeds.
1874: */
1875: boolean eglDestroySurface(EGLDisplay display, EGLSurface surface);
1876:
1877: /**
1878: * Return EGL surface information.
1879: *
1880: * <p><code>eglQuerySurface</code> returns in <code>value[0]</code> the
1881: * <code>value</code> of <code>attribute</code> for
1882: * <code>surface</code>. <code>attribute</code> can be one of the
1883: * following:
1884: *
1885: * <ul>
1886: *
1887: * <li><code>EGL_CONFIG_ID</code></li>
1888: *
1889: * <p>Returns the ID of the EGL frame buffer configuration with respect
1890: * to which the surface was created.
1891: *
1892: * <li><code>EGL_WIDTH</code></li>
1893: *
1894: * <p>Returns the width of the surface in pixels.
1895: *
1896: * <li><code>EGL_HEIGHT</code></li>
1897: *
1898: * <p>Returns the height of the surface in pixels.
1899: *
1900: * <li><code>EGL_LARGEST_PBUFFER</code></li>
1901: *
1902: * <p>Returns the same attribute value specified when the surface was
1903: * created with <code>eglCreatePbufferSurface</code>. For a window
1904: * or pixmap surface, value is not modified.
1905: *
1906: * <li><code>EGL_TEXTURE_FORMAT</code> (1.1 only)</li>
1907: *
1908: * <p>Returns format of texture. Possible values are
1909: * <code>EGL_NO_TEXTURE</code>, <code>EGL_TEXTURE_RGB</code>, and
1910: * <code>EGL_TEXTURE_RGBA</code>.
1911: *
1912: * <li><code>EGL_TEXTURE_TARGET</code> (1.1 only)</li>
1913: *
1914: * <p>Returns type of texture. Possible values are
1915: * <code>EGL_NO_TEXTURE</code>, or <code>EGL_TEXTURE_2D</code>.
1916: *
1917: * <li><code>EGL_MIPMAP_TEXTURE</code> (1.1 only)</li>
1918: *
1919: * <p>Returns <code>EGL_TRUE</code> if texture has mipmaps,
1920: * <code>EGL_FALSE</code> otherwise.
1921: *
1922: * <li><code>EGL_MIPMAP_LEVEL</code> (1.1 only)</li>
1923: *
1924: * <p>Returns which level of the mipmap to render to, if texture has mipmaps.
1925: *
1926: * </ul>
1927: *
1928: * <h4>1.1 Notes</h4>
1929: *
1930: * Querying <code>EGL_TEXTURE_FORMAT</code>,
1931: * <code>EGL_TEXTURE_TARGET</code>, <code>EGL_MIPMAP_TEXTURE</code>,
1932: * or <code>EGL_MIPMAP_LEVEL</code> for a non-pbuffer surface is not
1933: * an error, but <code>value</code> is not modified.
1934: *
1935: * <h4>Errors</h4>
1936: *
1937: * <p><code>false</code> is returned on failure, <code>true</code>
1938: * otherwise. <code>value</code> is not modified when
1939: * <code>false</code> is returned.
1940: *
1941: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
1942: * is not an EGL display connection.
1943: *
1944: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
1945: * <code>display</code> has not been initialized.
1946: *
1947: * <p><code>EGL_BAD_SURFACE</code> is generated if <code>surface</code>
1948: * is not an EGL surface.
1949: *
1950: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
1951: * <code>attribute</code> is not a valid surface attribute.
1952: *
1953: * @param display Specifies the EGL display connection.
1954: * @param surface Specifies the EGL surface to query.
1955: * @param attribute Specifies the EGL surface attribute to be returned.
1956: * @param value Returns the requested value.
1957: *
1958: * @exception IllegalArgumentException if <code>display</code> is
1959: * <code>null</code>.
1960: * @exception IllegalArgumentException if <code>surface</code> is
1961: * <code>null</code>.
1962: * @exception IllegalArgumentException if <code>value</code> is
1963: * <code>null</code> or has length less than 1.
1964: *
1965: * @return <code>true</code> if the query succeeds.
1966: */
1967: boolean eglQuerySurface(EGLDisplay display, EGLSurface surface,
1968: int attribute, int[] value);
1969:
1970: /**
1971: * Create a new EGL rendering context.
1972: *
1973: * <p><code>eglCreateContext</code> creates an EGL rendering context
1974: * and returns its handle. This context can be used to render into
1975: * an EGL drawing surface. If <code>eglCreateContext</code> fails to
1976: * create a rendering context, <code>EGL_NO_CONTEXT</code> is
1977: * returned.
1978: *
1979: * <p>If <code>share_context</code> is not <code>EGL_NO_CONTEXT</code>,
1980: * then all texture objects except object 0, are shared by context
1981: * <code>share_context</code> and by the newly created context. An
1982: * arbitrary number of rendering contexts can share a single texture
1983: * object space. However, all rendering contexts that share a single
1984: * texture object space must themselves exist in the same address
1985: * space. Two rendering contexts share an address space if both are
1986: * owned by a single process.
1987: *
1988: * <p> Currently no attributes are recognized, so
1989: * <code>attrib_list</code> will normally be <code>null</code> or
1990: * empty (first attribute is <code>EGL_NONE</code>). However, it is
1991: * possible that some platforms will define attributes specific to
1992: * those environments, as an EGL extension. A non-<code>null</code>
1993: * attribute list that is terminated with <code>EGL_NONE</code> will
1994: * be passed to the underlying EGL implementation.
1995: *
1996: * <!--
1997: * <h4>Notes</h4>
1998: *
1999: * <p>A process is a single execution environment, implemented in a
2000: * single address space, consisting of one or more threads.
2001: *
2002: * <p>A thread is one of a set of subprocesses that share a single
2003: * address space, but maintain separate program counters, stack
2004: * spaces, and other related global data. A thread is the only
2005: * member of its subprocess group is equivalent to a process.
2006: * -->
2007: *
2008: * <h4>Errors</h4>
2009: *
2010: * <p><code>EGL_NO_CONTEXT</code> is returned if creation of the
2011: * context fails.
2012: *
2013: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2014: * is not an EGL display connection.
2015: *
2016: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2017: * <code>display</code> has not been initialized.
2018: *
2019: * <p><code>EGL_BAD_CONFIG</code> is generated if <code>config</code>
2020: * is not an EGL frame buffer configuration.
2021: *
2022: * <p><code>EGL_BAD_CONTEXT</code> is generated if
2023: * <code>share_context</code> is not an EGL rendering context and is
2024: * not <code>EGL_NO_CONTEXT</code>.
2025: *
2026: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
2027: * <code>attrib_list</code> contains an invalid context attribute or
2028: * if an attribute is not recognized or out of range.
2029: *
2030: * <p><code>EGL_BAD_ALLOC</code> is generated if there are not enough
2031: * resources to allocate the new context.
2032: *
2033: * @param display Specifies the EGL display connection.
2034: * @param config Specifies the EGL frame buffer configuration that
2035: * defines the frame buffer resource available to the rendering
2036: * context.
2037: * @param share_context Specifies the EGL rendering context with
2038: * which to share texture objects. <code>EGL_NO_CONTEXT</code>
2039: * indicates that no sharing is to take place.
2040: * @param attrib_list Specifies attributes.
2041: *
2042: * @return A new <code>EGLContext</code>, or <code>null</code>
2043: * if context creation was unsuccessful.
2044: *
2045: * @exception IllegalArgumentException if <code>display</code> is
2046: * <code>null</code>.
2047: * @exception IllegalArgumentException if <code>config</code> is
2048: * <code>null</code>.
2049: * @exception IllegalArgumentException if <code>share_context</code> is
2050: * <code>null</code>.
2051: * @exception IllegalArgumentException if <code>attrib_list</code> is
2052: * non-<code>null</code> but is not terminated with
2053: * <code>EGL_NONE</code>.
2054: */
2055: EGLContext eglCreateContext(EGLDisplay display, EGLConfig config,
2056: EGLContext share_context, int[] attrib_list);
2057:
2058: /**
2059: * Destroy an EGL rendering context.
2060: *
2061: * <p>If the EGL rendering context context is not current to any
2062: * thread, <code>eglDestroyContext</code> destroys it
2063: * immediately. Otherwise, <code>context</code> is destroyed when it
2064: * becomes not current to any thread.
2065: *
2066: * <h4>Errors</h4>
2067: *
2068: * <p><code>false</code> is returned if destruction of the context
2069: * fails, <code>true</code> otherwise.
2070: *
2071: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2072: * is not an EGL display connection.
2073: *
2074: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2075: * <code>display</code> has not been initialized.
2076: *
2077: * <p><code>EGL_BAD_CONTEXT</code> is generated if <code>context</code>
2078: * is not an EGL rendering context.
2079: *
2080: * @param display Specifies the EGL display connection.
2081: * @param context Specifies the EGL rendering context to be destroyed.
2082: *
2083: * @exception IllegalArgumentException if <code>display</code> is
2084: * <code>null</code>.
2085: * @exception IllegalArgumentException if <code>context</code> is
2086: * <code>null</code>.
2087: *
2088: * @return <code>true</code> if the operation succeeds.
2089: */
2090: boolean eglDestroyContext(EGLDisplay display, EGLContext context);
2091:
2092: /**
2093: * Attach an EGL rendering context to EGL surfaces.
2094: *
2095: * <p><code>eglMakeCurrent</code> binds <code>context</code> to the
2096: * current rendering thread and to the <code>draw</code> and
2097: * <code>read</code> surfaces. <code>draw</code> is used for all GL
2098: * operations except for any pixel data read back
2099: * (<code>glReadPixels</code>, <code>glCopyTexImage2D</code>, and
2100: * <code>glCopyTexSubImage2D</code>), which is taken from the frame
2101: * buffer values of <code>read</code>.
2102: *
2103: * <p>If the calling thread has already a current rendering context,
2104: * that context is flushed and marked as no longer current.
2105: *
2106: * <p>The first time that context is made current, the viewport and
2107: * scissor dimensions are set to the size of the <code>draw</code>
2108: * surface. The viewport and scissor are not modified when
2109: * <code>context</code> is subsequently made current.
2110: *
2111: * <p>To release the current context without assigning a new one, call
2112: * eglMakeCurrent with <code>draw</code> and <code>read</code> set
2113: * to <code>EGL_NO_SURFACE</code> and <code>context</code> set to
2114: * <code>EGL_NO_CONTEXT</code>.
2115: *
2116: * <p>Use <code>eglGetCurrentContext</code>,
2117: * <code>eglGetCurrentDisplay</code>, and
2118: * <code>eglGetCurrentSurface</code> to query the current rendering
2119: * context and associated display connection and surfaces.
2120: *
2121: * <h4>Errors</h4>
2122: *
2123: * <p><code>false</code> is returned on failure,
2124: * <code>true</code> otherwise. If <code>false</code> is
2125: * returned, the previously current rendering context and surfaces
2126: * (if any) remain unchanged.
2127: *
2128: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2129: * is not an EGL display connection.
2130: *
2131: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2132: * <code>display</code> has not been initialized.
2133: *
2134: * <p><code>EGL_BAD_SURFACE</code> is generated if <code>draw</code> or
2135: * <code>read</code> is not an EGL surface.
2136: *
2137: * <p><code>EGL_BAD_CONTEXT</code> is generated if <code>context</code>
2138: * is not an EGL rendering context.
2139: *
2140: * <p><code>EGL_BAD_MATCH</code> is generated if <code>draw</code> or
2141: * <code>read</code> are not compatible with context, or if
2142: * <code>context</code> is set to <code>EGL_NO_CONTEXT</code> and
2143: * <code>draw</code> or <code>read</code> are not set to
2144: * <code>EGL_NO_SURFACE</code>, or if <code>draw</code> or
2145: * <code>read</code> are set to <code>EGL_NO_SURFACE</code> and
2146: * <code>context</code> is not set to <code>EGL_NO_CONTEXT</code>.
2147: *
2148: * <p><code>EGL_BAD_ACCESS</code> is generated if <code>context</code>
2149: * is current to some other thread.
2150: *
2151: * <p><code>EGL_BAD_NATIVE_PIXMAP</code> may be generated if a native
2152: * pixmap underlying either <code>draw</code> or <code>read</code>
2153: * is no longer valid.
2154: *
2155: * <p><code>EGL_BAD_NATIVE_WINDOW</code> may be generated if a native
2156: * window underlying either <code>draw</code> or <code>read</code>
2157: * is no longer valid.
2158: *
2159: * <p><code>EGL_BAD_CURRENT_SURFACE</code> is generated if the previous
2160: * context has unflushed commands and the previous surface is no
2161: * longer valid.
2162: *
2163: * <p><code>EGL_BAD_ALLOC</code> may be generated if allocation of
2164: * ancillary buffers for draw or read were delayed until
2165: * <code>eglMakeCurrent</code> is called, and there are not enough
2166: * resources to allocate them.
2167: *
2168: * <p><code>EGL_CONTEXT_LOST</code> (1.1 only)
2169: *
2170: * <p>A power management event has occurred. The application must
2171: * destroy all contexts and reinitialise OpenGL ES state and objects
2172: * to continue rendering.
2173: *
2174: * @param display Specifies the EGL display connection.
2175: * @param draw Specifies the EGL draw surface.
2176: * @param read Specifies the EGL read surface.
2177: * @param context Specifies the EGL rendering context to be attached
2178: * to the surfaces.
2179: *
2180: * @exception IllegalArgumentException if <code>display</code> is
2181: * <code>null</code>.
2182: * @exception IllegalArgumentException if <code>draw</code> is
2183: * <code>null</code>.
2184: * @exception IllegalArgumentException if <code>read</code> is
2185: * <code>null</code>.
2186: * @exception IllegalArgumentException if <code>context</code> is
2187: * <code>null</code>.
2188: *
2189: * @return <code>true</code> if the operation succeeds.
2190: */
2191: boolean eglMakeCurrent(EGLDisplay display, EGLSurface draw,
2192: EGLSurface read, EGLContext context);
2193:
2194: /**
2195: * Return the current EGL rendering context.
2196: *
2197: * <p><code>eglGetCurrentContext</code> returns the current EGL
2198: * rendering context, as specified by
2199: * <code>eglMakeCurrent</code>. If no context is current,
2200: * <code>EGL_NO_CONTEXT</code> is returned.
2201: *
2202: * @return The current <code>EGLContext</code>, or
2203: * <code>EGL_NO_CONTEXT</code>.
2204: */
2205: EGLContext eglGetCurrentContext();
2206:
2207: /**
2208: * Return the read or draw surface for the current EGL rendering
2209: * context.
2210: *
2211: * <p><code>eglGetCurrentSurface</code> returns the read or draw
2212: * surface attached to the current EGL rendering context, as
2213: * specified by <code>eglMakeCurrent</code>. If no context is
2214: * current, <code>EGL_NO_SURFACE</code> is returned.
2215: *
2216: * @param readdraw Specifies whether the EGL read or draw surface is
2217: * to be returned, one of <code>EGL_READ</code> or
2218: * <code>EGL_DRAW</code>.
2219: * @return The current <code>EGLSurface</code> used for reading (if
2220: * <code>readdraw</code> equals <code>EGL_READ</code>, or drawing
2221: * (if <code>readdraw</code> equals <code>EGL_DRAW</code>).
2222: *
2223: * @exception IllegalArgumentException if <code>readdraw</code> is
2224: * not one of the specified constants.
2225: */
2226: EGLSurface eglGetCurrentSurface(int readdraw);
2227:
2228: /**
2229: * Return the display for the current EGL rendering context.
2230: *
2231: * <p><code>eglGetCurrentDisplay</code> returns the current EGL display
2232: * connection for the current EGL rendering context, as specified by
2233: * <code>eglMakeCurrent</code>. If no context is current,
2234: * <code>EGL_NO_DISPLAY</code> is returned.
2235: *
2236: * @return The current <code>EGLDisplay</code>
2237: */
2238: EGLDisplay eglGetCurrentDisplay();
2239:
2240: /**
2241: * Return EGL rendering context information.
2242: *
2243: * <p><code>eglQueryContext</code> returns in <code>value[0]</code> the
2244: * value of <code>attribute</code> for
2245: * <code>context</code>. <code>attribute</code> can be one of the
2246: * following:
2247: *
2248: * <ul>
2249: *
2250: * <li><code>EGL_CONFIG_ID</code></li>
2251: *
2252: * <p>Returns the ID of the EGL frame buffer configuration with respect
2253: * to which the context was created.
2254: *
2255: * </ul>
2256: *
2257: * <h4>Errors</h4>
2258: *
2259: * <p><code>false</code> is returned on failure, <code>true</code>
2260: * otherwise. <code>value</code> is not modified when
2261: * <code>false</code> is returned.
2262: *
2263: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2264: * is not an EGL display connection.
2265: *
2266: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2267: * <code>display</code> has not been initialized.
2268: *
2269: * <p><code>EGL_BAD_CONTEXT</code> is generated if <code>context</code>
2270: * is not an EGL rendering context.
2271: *
2272: * <p><code>EGL_BAD_ATTRIBUTE</code> is generated if
2273: * <code>attribute</code> is not a valid context attribute.
2274: *
2275: * @param display Specifies the EGL display connection.
2276: * @param context Specifies the EGL rendering context to query.
2277: * @param attribute Specifies the EGL rendering context attribute to
2278: * be returned.
2279: * @param value Returns the requested value.
2280: *
2281: * @exception IllegalArgumentException if <code>display</code> is
2282: * <code>null</code>.
2283: * @exception IllegalArgumentException if <code>context</code> is
2284: * <code>null</code>.
2285: * @exception IllegalArgumentException if <code>value</code> is
2286: * <code>null</code> or has length less than 1.
2287: *
2288: * @return <code>true</code> if the query succeeds.
2289: */
2290: boolean eglQueryContext(EGLDisplay display, EGLContext context,
2291: int attribute, int[] value);
2292:
2293: /**
2294: * Complete GL execution prior to subsequent native rendering calls.
2295: *
2296: * <p>GL rendering calls made prior to <code>eglWaitGL</code> are
2297: * guaranteed to be executed before native rendering calls made
2298: * after <code>eglWaitGL</code>. The same result can be achieved
2299: * using <code>glFinish</code>.
2300: *
2301: * <p><code>eglWaitGL</code> is ignored if there is no current EGL
2302: * rendering context.
2303: *
2304: * <h4>Errors</h4>
2305: *
2306: * <p><code>false</code> is returned if <code>eglWaitGL</code> fails,
2307: * <code>true</code> otherwise.
2308: *
2309: * <p><code>EGL_BAD_NATIVE_SURFACE</code> is generated if the surface
2310: * associated with the current context has a native window or
2311: * pixmap, and that window or pixmap is no longer valid.
2312: *
2313: * @return <code>true</code> if the operation succeeds.
2314: */
2315: boolean eglWaitGL();
2316:
2317: /**
2318: * Complete native execution prior to subsequent GL rendering calls.
2319: *
2320: * <p>Native rendering calls made prior to <code>eglWaitNative</code>
2321: * are guaranteed to be executed before GL rendering calls made
2322: * after <code>eglWaitNative</code>.
2323: *
2324: * <p><code>eglWaitNative</code> is ignored if there is no current EGL
2325: * rendering context.
2326: *
2327: * <h4>Notes</h4>
2328: *
2329: * <p>In a MIDP environment, OpenGL ES drawing to an <code>Image</code>,
2330: * <code>Canvas</code>, or <code>GameCanvas</code> must be preceded
2331: * by a call to
2332: * <code>eglWaitNative(<code>EGL10.EGL_CORE_NATIVE_ENGINE</code>,
2333: * graphics)</code> and followed by a call to
2334: * <code>eglWaitGL()</code>. The <code>bindTarget</code> parameter
2335: * must be the instance of
2336: * <code>javax.microedition.lcdui.Graphics</code> obtained from the
2337: * <code>GameCanvas.getGraphics</code> method (if drawing to a
2338: * <code>GameCanvas</code>), from the <code>Image.getGraphics()</code>
2339: * method (if drawing to a mutable <code>Image</code>),
2340: * or the instance obtained as the
2341: * parameter to the <code>Canvas.paint</code> method (if drawing to
2342: * a <code>Canvas</code>).
2343: *
2344: * <p>The results of passing improper values for <code>engine</code>
2345: * and/or <code>bindTarget</code> are undefined.
2346: *
2347: * <p> The results of MIDP drawing calls are undefined from the time
2348: * of the call to <code>eglWaitNative</code> until
2349: * <code>eglWaitGL</code> returns.
2350: *
2351: * <h4>Errors</h4>
2352: *
2353: * <p><code>EGL_BAD_PARAMETER</code> is generated if
2354: * <code>engine</code> is not a recognized marking engine.
2355: *
2356: * <p><code>EGL_BAD_NATIVE_SURFACE</code> is generated if the surface
2357: * associated with the current context has a native window or
2358: * pixmap, and that window or pixmap is no longer valid.
2359: *
2360: * @param engine Specifies a particular marking engine to be waited
2361: * on. Must be <code>EGL_CORE_NATIVE_ENGINE</code>.
2362: * @param bindTarget the rendering target shared by the native
2363: * engine and the EGL drawing surface. For MIDP, must be the
2364: * instance of <code>javax.microedition.lcdui.Graphics</code>
2365: * representing the targetted <code>Canvas</code>, <code>Image</code>, or
2366: * <code>GameCanvas</code>.
2367: *
2368: * @return <code>true</code> if the operation succeeds.
2369: */
2370: boolean eglWaitNative(int engine, Object bindTarget);
2371:
2372: /**
2373: * Post EGL surface color buffer to a native window.
2374: *
2375: * <p>If surface is a window surface, <code>eglSwapBuffers</code> posts
2376: * its color buffer to the associated native window.
2377: *
2378: * <p><code>eglSwapBuffers</code> performs an implicit
2379: * <code>glFlush</code> before it returns. Subsequent GL commands
2380: * may be issued immediately after calling
2381: * <code>eglSwapBuffers</code>, but are not executed until the
2382: * buffer exchange is completed.
2383: *
2384: * <p>If surface is a pixel buffer or a pixmap,
2385: * <code>eglSwapBuffers</code> has no effect, and no error is
2386: * generated.
2387: *
2388: * <h4>Notes</h4>
2389: *
2390: * <p>The color buffer of surface is left undefined after calling
2391: * <code>eglSwapBuffers</code>.
2392: *
2393: * <p>On the CLDC/MIDP plaform, calling <code>eglSwapBuffers</code>
2394: * is equivalent to calling <code>glFinish</code> when drawing to a
2395: * <code>GameCanvas</code>. The
2396: * <code>GameCanvas.flushGraphics</code> method is used to copy the
2397: * contents of the back buffer to the screen.
2398: *
2399: * <h4>Errors</h4>
2400: *
2401: * <p><code>false</code> is returned if swapping of the surface
2402: * buffers fails, <code>true</code> otherwise.
2403: *
2404: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2405: * is not an EGL display connection.
2406: *
2407: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2408: * <code>display</code> has not been initialized.
2409: *
2410: * <p><code>EGL_BAD_SURFACE</code> is generated if <code>surface</code>
2411: * is not an EGL drawing surface.
2412: *
2413: * <p><code>EGL_CONTEXT_LOST</code> (1.1 only)
2414: *
2415: * <p>A power management event has occurred. The application must
2416: * destroy all contexts and reinitialise OpenGL ES state and objects
2417: * to continue rendering.
2418: *
2419: * @param display Specifies the EGL display connection.
2420: * @param surface Specifies the EGL drawing surface whose buffers
2421: * are to be swapped.
2422: *
2423: * @exception IllegalArgumentException if <code>display</code> is
2424: * <code>null</code>.
2425: * @exception IllegalArgumentException if <code>surface</code> is
2426: * <code>null</code>.
2427: *
2428: * @return <code>true</code> if the operation succeeds.
2429: */
2430: boolean eglSwapBuffers(EGLDisplay display, EGLSurface surface);
2431:
2432: /**
2433: * Copy EGL surface color buffer to a native pixmap.
2434: *
2435: * <p><code>eglCopyBuffers</code> copies the color buffer of
2436: * <code>surface</code> to <code>native_pixmap</code>.
2437: *
2438: * <p><code>eglCopyBuffers</code> performs an implicit
2439: * <code>glFlush</code> before it returns. Subsequent GL commands
2440: * may be issued immediately after calling
2441: * <code>eglCopyBuffers</code>, but are not executed until copying
2442: * of the color buffer is completed.
2443: *
2444: * <h4>Notes</h4>
2445: *
2446: * <p>The color buffer of surface is left unchanged after calling
2447: * <code>eglCopyBuffers</code>.
2448: *
2449: * <p>On JME CLDC/MIDP platforms, <code>native_pixmap</code> must be
2450: * an instance of <code>javax.microedition.lcdui.Image</code> that
2451: * is mutable, or an instance of
2452: * <code>javax.microedition.lcdui.Graphics</code>
2453: * that was obtained directly from such
2454: * an image by means of a call to <code>createGraphics()</code> or
2455: * <code>getGraphics()</code>.
2456: *
2457: * <!--
2458: * <p>On JME Personal Basis Profile and Personal Profile platforms,
2459: * <code>native_pixmap</code> must be an instance of
2460: * <code>java.awt.image.BufferedImage</code>, or an instance of
2461: * <code>java.awt.Graphics</code> that was obtained directly from
2462: * such an image by means of a call to <code>createGraphics()</code>
2463: * or <code>getGraphics()</code>.
2464: * -->
2465: *
2466: * <h4>Errors</h4>
2467: *
2468: * <p><code>false</code> is returned if swapping of the surface
2469: * buffers fails, <code>true</code> otherwise.
2470: *
2471: * <p><code>EGL_BAD_DISPLAY</code> is generated if <code>display</code>
2472: * is not an EGL display connection.
2473: *
2474: * <p><code>EGL_NOT_INITIALIZED</code> is generated if
2475: * <code>display</code> has not been initialized.
2476: *
2477: * <p><code>EGL_BAD_SURFACE</code> is generated if <code>surface</code>
2478: * is not an EGL drawing surface.
2479: *
2480: * <p><code>EGL_BAD_NATIVE_PIXMAP</code> is generated if the
2481: * implementation does not support native pixmaps.
2482: *
2483: * <p><code>EGL_BAD_NATIVE_PIXMAP</code> may be generated if
2484: * <code>native_pixmap</code> is not a valid native pixmap.
2485: *
2486: * <p><code>EGL_BAD_MATCH</code> is generated if the format of
2487: * <code>native_pixmap</code> is not compatible with the color
2488: * buffer of surface.
2489: *
2490: * <p>(1.1 only) <code>EGL_CONTEXT_LOST</code> is generated if a
2491: * power management event has occurred. The application must destroy
2492: * all contexts and reinitialize OpenGL ES state and objects to
2493: * continue rendering.
2494: *
2495: * @param display Specifies the EGL display connection.
2496: * @param surface Specifies the EGL surface whose color buffer is to
2497: * be copied.
2498: * @param native_pixmap Specifies the native pixmap as target of the
2499: * copy.
2500: *
2501: * @exception IllegalArgumentException if <code>display</code> is
2502: * <code>null</code>.
2503: * @exception IllegalArgumentException if <code>surface</code> is
2504: * <code>null</code>.
2505: * @exception IllegalArgumentException if <code>native_pixmap</code>
2506: * is <code>null</code> or is not of a suitable type for the
2507: * underlying platform (e.g., a mutable <code>Image</code> for CLDC/MIDP).
2508: *
2509: * @return <code>true</code> if the copy succeeds.
2510: */
2511: boolean eglCopyBuffers(EGLDisplay display, EGLSurface surface,
2512: Object native_pixmap);
2513: }
|