Return to glGetString.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="glGetString">
  <refmeta>
    <refentrytitle>glGetString</refentrytitle>
    <manvolnum>3G</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>glGetString</refname>
    <refpurpose>return a string describing the current GL
    connection</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>C Specification</title>

    <funcsynopsis>
      <funcprototype>
        <funcdef>const GLubyte * <function>glGetString</function></funcdef>
        <paramdef>GLenum <parameter>name</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>
          <parameter>name</parameter>
        </term>

        <listitem>
          <para>Specifies a symbolic constant, one of 
          <constant>GL_VENDOR</constant>, 
          <constant>GL_RENDERER</constant>, 
          <constant>GL_VERSION</constant>, or 
          <constant>GL_EXTENSIONS</constant>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <para><function>glGetString</function>
    returns a pointer to a static string describing some aspect of
    the current GL connection.  <parameter>name</parameter>
    can be one of the following:</para>

    <variablelist>
      <varlistentry>
        <term>
          <constant>GL_VENDOR</constant>
        </term>

        <listitem>
          <para>Returns the company responsible for this GL
          implementation. This name does not change from release to
          release.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_RENDERER</constant>
        </term>

        <listitem>
          <para>Returns the name of the renderer. This name is
          typically specific to a particular configuration of a
          hardware platform. It does not change from release to
          release.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_VERSION</constant>
        </term>

        <listitem>
          <para>Returns a version or release number.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <constant>GL_EXTENSIONS</constant>
        </term>

        <listitem>
          <para>Returns a space-separated list of supported
          extensions to GL.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Because the GL does not include queries for the
    performance characteristics of an implementation, some
    applications are written to recognize known platforms and
    modify their GL usage based on known performance
    characteristics of these platforms. Strings 
    <constant>GL_VENDOR</constant> and 
    <constant>GL_RENDERER</constant> 
    together uniquely specify a platform. They do not change from
    release to release and should be used by platform-recognition
    algorithms.</para>

    <para>Some applications want to make use of features that are
    not part of the standard GL. These features may be implemented
    as extensions to the standard GL. The <constant>GL_EXTENSIONS</constant>
    string is a space-separated list of supported GL extensions.
    (Extension names never contain a space character.)</para>

    <para>The <constant>GL_VERSION</constant>
    string begins with a version number. The version number uses
    one of these forms:</para>

    <para><replaceable>major_number</replaceable>.<replaceable>minor_number</replaceable></para>

    <para><replaceable>major_number</replaceable>.<replaceable>minor_number</replaceable>.<replaceable>release_number</replaceable></para>

    <para>Vendor-specific information may follow the version
    number. Its depends on the implementation, but a space always
    separates the version number and the vendor-specific
    information.</para>

    <para>All strings are null-terminated.</para>
  </refsect1>

  <refsect1>
    <title>Notes</title>

    <para>If an error is generated, <function>glGetString</function>
    returns <constant>NULL</constant>.</para>

    <para>The client and server may support different versions or
    extensions.  <function>glGetString</function>
    always returns a compatible version number or list of
    extensions. The release number always describes the
    server.</para>
  </refsect1>

  <refsect1>
    <title>Errors</title>

    <para><constant>GL_INVALID_ENUM</constant> is generated if 
    <parameter>name</parameter> is not an accepted value.</para>
  </refsect1>
</refentry>