Return to eglIntro.xml CVS log

Up to [Development] / projects / ogl-sample / main / doc / gles / xml

OpenGL ES 1.0 and EGL 1.0 reference manual and man pages (written by
Claude Knaus, based on OpenGL SI man pages).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "DTD/docbook/docbookx.dtd">

<!--
  License Applicability. Except to the extent portions of this file are
  made subject to an alternative license as permitted in the SGI Free
  Software License B, Version 1.1 (the "License"), the contents of this
  file are subject only to the provisions of the License. You may not use
  this file except in compliance with the License. You may obtain a copy
  of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
  Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:

  http://oss.sgi.com/projects/FreeB

  Note that, as provided in the License, the Software is distributed on an
  "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
  DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
  CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
  PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

  Original Code. The Original Code is: OpenGL ES Reference Manual,
  Version 1.0, released September 2003, developed by Silicon Graphics,
  Inc.  The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
  Copyright in any portions created by third parties is as indicated
  elsewhere herein.  All Rights Reserved.
-->

<refentry id="eglIntro">

  <refmeta>
    <refentrytitle>eglIntro</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>eglIntro</refname>
    <refpurpose>
      introduction to <acronym>OpenGL ES</acronym> in an
      <acronym>EGL</acronym> window system
    </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Overview</title>

    <para>
      OpenGL ES (GL) is a 3D-oriented renderer for embedded systems.
      It is made available through the <firstterm>OpenGL ES Native Platform Graphics
      Interface</firstterm> (EGL). Depending on its implementation
      EGL might be more or less tightly integrated into the native window
      system. Most EGL functions require an EGL display connection, which
      can be obtained by calling
      <citerefentry><refentrytitle>eglGetDisplay</refentrytitle></citerefentry>
      and passing in a native display handler or
      <constant>EGL_DEFAULT_DISPLAY</constant>. To initialize and query what
      EGL version is supported on the display connection, call
      <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry>.
    </para>

    <para>
      Native window systems supporting EGL make a subset of their visuals
      available for GL rendering. Windows and pixmaps created with these
      visuals may also be rendered into using the native window system API.
    </para>

    <para>
      EGL extends a native window or pixmap with additional buffers.
      These buffers include a color buffer, a depth buffer, and a stencil
      buffer. Some or all of the buffers listed are included in each
      EGL frame buffer configuration.
    </para>

    <para>
      EGL supports rendering into three types of surfaces: windows, pixmaps
      and pixel buffers (pbuffers). EGL window and pixmap surfaces are
      associated with corresponding resources of the native window system.
      EGL pixel buffers are EGL only resources, and might not accept rendering
      through the native window system.
    </para>

    <para>
      To render using OpenGL ES into an EGL surface, you must determine the
      appropriate EGL frame buffer configuration, which supports the rendering
      features the application requires.
      <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>
      returns an <type>EGLConfig</type> matching the required attributes, if
      any. A complete list of EGL frame buffer configurations can be obtained
      by calling <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>.
      Attributes of a particular EGL frame buffer configuration can be queried by
      calling <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>.
    </para>

    <para>
      For EGL window and pixmap surfaces, a suitable native window or pixmap
      with a matching native visual must be created first. For a given EGL
      frame buffer configuration, the native visual type and ID can be retrieved
      with a call to
<citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>.
      For pixel buffers, no underlying native resource is required.
    </para>

    <para>
      To create an EGL window surface from a native window, call
<citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>.

      Likewise, to create an EGL pixmap surface, call
<citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>.
      Pixel buffers are created by calling
<citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>
      Use
      <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>
      to release previously allocated resources.
    </para>

    <para>
     An EGL rendering context is required to bind OpenGL ES rendering to an EGL
     surface. An EGL surface and an EGL rendering context must have compatible
     EGL frame buffer configurations. To
     create an EGL rendering context, call
<citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>
     An EGL rendering context may be bound to one or two EGL surfaces by calling
<citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>.
     This context/surfaces association becomes the current context and
     current surfaces, and is used by all GL rendering commands until
<citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> is
     called with different arguments.
   </para>

   <para>
     Both native and GL commands may be used to operate on certain surfaces,
     however, the two command streams are not synchronized.
     Synchronization can be explicitly specified using by calling
<citerefentry><refentrytitle>eglWaitGL</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglWaitNative</refentrytitle></citerefentry>,
     and possibly by calling other native window system commands.
   </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <para>
      Below is a minimal example of creating an RGBA-format window that
      allows rendering with OpenGL ES.
      The window is cleared to yellow when the program runs. For simplicity,
      the program does not check for any errors.
    </para>

<programlisting>
#include &lt;stdlib.h&gt;
#include &lt;unistd.h&gt;
#include &lt;GLES/egl.h&gt;
#include &lt;GLES/gl.h&gt;

typedef ... NativeWindowType;
extern NativeWindowType createNativeWindow(void);

static EGLint const attribute_list[] = {
    EGL_RED_SIZE, 1,
    EGL_GREEN_SIZE, 1,
    EGL_BLUE_SIZE, 1,
    EGL_NONE
};

int main(int argc, char ** argv)
{
    EGLDisplay display;
    EGLConfig config;
    EGLContext context;
    EGLSurface surface;
    NativeWindowType native_window;
    EGLint num_config;
 
    /* get an EGL display connection */
    display = eglGetDisplay(EGL_DEFAULT_DISPLAY);

    /* initialize the EGL display connection */
    eglInitialize(display, NULL, NULL);

    /* get an appropriate EGL frame buffer configuration */
    eglChooseConfig(display, attribute_list, &amp;config, 1, &amp;num_config);

    /* create an EGL rendering context */
    context = eglCreateContext(display, config, EGL_NO_CONTEXT, NULL);

    /* create a native window */
    native_window = createNativeWindow();

    /* create an EGL window surface */
    surface = eglCreateWindowSurface(display, config, native_window, NULL);

    /* connect the context to the surface */
    eglMakeCurrent(display, surface, surface, context);

    /* clear the color buffer */
    glClearColor(1.0, 1.0, 0.0, 1.0);
    glClear(GL_COLOR_BUFFER_BIT);
    glFlush();

    eglSwapBuffers(display, surface);

    sleep(10);

    return EXIT_SUCCESS;
}
</programlisting>
  </refsect1>

  <refsect1>
    <title>Using EGL Extensions</title>

    <para>
      All supported EGL extensions will have a corresponding definition in
      <filename>egl.h</filename> and a token in the extensions string returned
      by
      <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>.
    
      For extensions in OpenGL ES, refer to
      <citerefentry><refentrytitle>glIntro</refentrytitle></citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>Future EGL Versions</title>

    <para>
      <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry>
      and
      <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>
      can be used to determine at run-time what version of EGL is available.
      To check the EGL version at compile-time, test whether
      <constant>EGL_VERSION_<replaceable>x</replaceable>_<replaceable>y</replaceable></constant>
      is defined, where <replaceable>x</replaceable> and
      <replaceable>y</replaceable> are the major and minor version
      numbers.
    </para>
  </refsect1>

  <refsect1>
    <title>Files</title>

    <variablelist>
      <varlistentry>
        <term><filename>GLES/egl.h</filename></term>
        <listitem><para>
          EGL header file
        </para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>glIntro</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglDestroyContext</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglGetDisplay</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglSwapBuffers</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglTerminate</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglWaitGL</refentrytitle></citerefentry>,
      <citerefentry><refentrytitle>eglWaitNative</refentrytitle></citerefentry>
    </para>
  </refsect1>

</refentry>