libgles.tex

python s60 1.4.5版本的源代码

% Copyright (c) 2005 Nokia Corporation
%
% Licensed under the Apache License, Version 2.0 (the "License");
% you may not use this file except in compliance with the License.
% You may obtain a copy of the License at
%
%     http://www.apache.org/licenses/LICENSE-2.0
%
% Unless required by applicable law or agreed to in writing, software
% distributed under the License is distributed on an "AS IS" BASIS,
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
% See the License for the specific language governing permissions and
% limitations under the License.

\section{\module{gles} ---
  Bindings to OpenGL ES}
\label{sec:gles}

\declaremodule{extension}{gles}
\platform{S60}
\modulesynopsis{Bindings to OpenGL ES.}

The \module{gles} module provides Python bindings to OpenGL ES 2D/3D graphics C
API. OpenGL ES is a standard defined by Khronos Group
(www.khronos.org). Currently S60 Python supports OpenGL ES version 1.0 from
Series 60 version 2.6 onwards. Support for OpenGL ES version 1.1 should also
become available in the near future, and both versions are documented
here. OpenGL ES 1.1 will require Series 60 version 3.0 or newer.

For detailed description of the OpenGL ES API see the official specifications at
http://www.khronos.org/opengles. This documentation contains only information
that is specific to the S60 Python bindings to OpenGL ES. Where possible, the
conventions of the PyOpenGL desktop OpenGL bindings
(http://pyopengl.sourceforge.net) have been followed.

The display of OpenGL ES graphics is handled by separate module,
\module{glcanvas}. See \module{glcanvas} module documentation for more
information.

\subsection{array type}

\module{gles} module defines \class{array} type for representing numerical data of
specific GL type. \class{array} objects are convenient when numerical data for
OpenGL ES calls is specified in Python code. Class \class{array} also defines
the standard Python sequence methods so its instances can be iterated and
individual items in arrays can be manipulated easily.

\begin{classdesc}{array}{type, dimension, sequence}
Constructs a new \class{array} object that contains the given type of data that
is taken from \var{sequence}. Parameter \var{dimension} specifies how many items
there are in each array element. The dimension information is stored with the
array and is used by those functions that need to know the element size of the
input data, for example, if colors are specified with three or four
components. The dimension does not affect the length of an array or its
indexing: both are based on individual items.

Value of \var{type} must be one of the following:
\code{GL_FLOAT}, \code{GL_BYTE}, \code{GL_UNSIGNED_BYTE}, \code{GL_SHORT},
\code{GL_UNSIGNED_SHORT}, or \code{GL_FIXED}.

The data in \var{sequence} is flattened before it is used to fill the
array. When \var{type} is \code{GL_FLOAT}, the sequence can contains floats or
integers. With all other types, \var{sequence} must only contain
integers. Values in \var{sequence} are casted in C to the requested type, so if
the requested type cannot properly represent all the values the results can be
unexpected.

\begin{methoddesc}[array]{__len__}{}
Returns the number of items in the array. Note that array dimension does not
affect the calculation of the length.
\end{methoddesc}

\begin{methoddesc}[array]{__getitem__}{index}
Returns the item in array with \var{index}. Note that array dimension does not
affect indexing.
\end{methoddesc}

\begin{methoddesc}[array]{__setitem__}{index, value}
Sets the value of the item in position \var{index} to \var{value}. Note that
array dimension does not affect indexing.
\end{methoddesc}
\end{classdesc}

\subsection{Error handling}

Errors generated by the API calls are handled similarly as in PyOpenGL: all GL
errors are reported as Python exceptions of type \class{gles.GLerror}. The
wrapper code checks GL error status after each call automatically. There is no
Python binding for \code{glGetError} call.

\subsection{Differences to OpenGL ES C API}
\label{subsec:differences}

Certain OpenGL ES functions require special handling in Python, mainly because
of the pointer parameters in the C API. Additionally, special Python versions for
some OpenGL ES functions have been added. Both of sets of functions are
documented below. If a function is not listed here its Python version should
exactly match the C version defined in the official OpenGL ES 1.0 and 1.1
specifications.

\subsubsection{OpenGL ES 1.0}

\begin{funcdesc}{glColorPointer}{size, type, stride, sequence}
Parameter \var{sequence} must be either a \class{gles.array} object or some other
Python sequence object. \class{gles.array} objects require less processing and can
be therefore slightly faster. If \class{gles.array} object is used, the type and
dimension of its data are ignored and \var{size} and \var{type} are used
instead.
\end{funcdesc}

\begin{funcdesc}{glColorPointerub}{sequence}
Special Python version of \code{glColorPointer} that accepts either a
\class{gles.array} object or some other Python sequence object. Other parameters
of \code{glColorPointer} will be determined as follows:
\begin{itemize}
\item \var{size} If \var{sequence} is an instance of \class{gles.array}, its dimension is used; otherwise the length of \var{sequence} is used.
\item \var{type} \code{GL_UNSIGNED_BYTE}
\item \var{stride} 0
\end{itemize}
\end{funcdesc}

\begin{funcdesc}{glColorPointerf}{sequence}
Special Python version of \code{glColorPointer} that behaves exactly as
\code{glColorPointerub} except \code{GL_FLOAT} is used as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glColorPointerx}{sequence}
Special Python version of \code{glColorPointer} that behaves exactly as
\code{glColorPointerub} except \code{GL_FIXED} is used as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glCompressedTexImage2D}{target, level, internalformat, width, height, border, imageSize, data}
Parameter \var{data} must be either a \class{gles.array} or a Python string.
\end{funcdesc}

\begin{funcdesc}{glCompressedTexSubImage2D}{target, level, xoffset, yoffset, width, height, format, imageSize, data}
Parameter \var{data} must be either a \class{gles.array} or a Python string.
\end{funcdesc}

\begin{funcdesc}{glDeleteTextures}{sequence}
Parameter \var{sequence} must be a Python sequence containing integers.
\end{funcdesc}

\begin{funcdesc}{glDrawElements}{mode, count, type, indices}
Parameter \var{indices} must be either a \class{gles.array} or some other Python
sequence object. \class{gles.array} objects require less processing and can be
therefore slightly faster. If \class{gles.array} object is used, the type of its
data is ignored and \var{type} is used instead.
\end{funcdesc}

\begin{funcdesc}{glDrawElementsub}{mode, indices}
Special Python version of \code{glDrawElements} that uses length of the sequence
\var{indices} as \var{count} and \code{GL_UNSIGNED_BYTE} as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glDrawElementsus}{mode, indices}
Special Python version of \code{glDrawElements} that uses length of the sequence
\var{indices} as \var{count} and \code{GL_UNSIGNED_SHORT} as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glFogv}{pname, params}
Parameter \var{params} must be a Python sequence containing float values.
\end{funcdesc}

\begin{funcdesc}{glFogxv}{pname, params}
Parameter \var{params} must be a Python sequence containing integer values.
\end{funcdesc}

\begin{funcdesc}{glGenTextures}{n}
The generated texture names are returned in a Python tuple.
\end{funcdesc}

\begin{funcdesc}{glGetIntegerv}{pname}
The values are returned in a Python tuple.
\end{funcdesc}

\begin{funcdesc}{glGetString}{name}
The value is return as a Python string.
\end{funcdesc}

\begin{funcdesc}{glLightModelfv}{pname, params}
Parameter \var{params} must be a Python sequence containing float values.
\end{funcdesc}

\begin{funcdesc}{glLightModelxv}{pname, params}
Parameter \var{params} must be a Python sequence containing integer values.
\end{funcdesc}

\begin{funcdesc}{glLightfv}{light, pname, params}
Parameter \var{params} must be a Python sequence containing float values.
\end{funcdesc}

\begin{funcdesc}{glLightxv}{light, pname, params}
Parameter \var{params} must be a Python sequence containing integer values.
\end{funcdesc}

\begin{funcdesc}{glLoadMatrixf}{m}
Parameter \var{m} must be a Python sequence containing float values. The sequence
is flattened before its items are read.
\end{funcdesc}

\begin{funcdesc}{glLoadMatrixx}{m}
Parameter \var{m} must be a Python sequence containing integer values. The
sequence is flattened before its items are read.
\end{funcdesc}

\begin{funcdesc}{glMaterialfv}{face, pname, params}
Parameter \var{params} must be a Python sequence containing float values.
\end{funcdesc}

\begin{funcdesc}{glMaterialxv}{face, pname, params}
Parameter \var{params} must be a Python sequence containing integer values.
\end{funcdesc}

\begin{funcdesc}{glMultMatrixf}{m}
Parameter \var{m} must be a Python sequence containing float values. The
sequence is flattened before its items are read.
\end{funcdesc}

\begin{funcdesc}{glMultMatrixx}{m}
Parameter \var{m} must be a Python sequence containing integer values. The
sequence is flattened before its items are read.
\end{funcdesc}

\begin{funcdesc}{glNormalPointer}{type, stride, sequence}
Parameter \var{sequence} must be either a \class{gles.array} object or some other
Python sequence object. \class{gles.array} objects require less processing and
can be therefore slightly faster. If \class{gles.array} object is used, the type
of its data is ignored and \var{type} is used instead.
\end{funcdesc}

\begin{funcdesc}{glNormalPointerb}{sequence}
Special Python version of \code{glNormalPointer} that uses \var{type}
\code{GL_BYTE} and \var{stride} 0.
\end{funcdesc}

\begin{funcdesc}{glNormalPointers}{sequence}
Special Python version of \code{glNormalPointer} that uses \var{type}
\code{GL_SHORT} and \var{stride} 0.
\end{funcdesc}

\begin{funcdesc}{glNormalPointerf}{sequence}
Special Python version of \code{glNormalPointer} that uses \var{type}
\code{GL_FLOAT} and \var{stride} 0.
\end{funcdesc}

\begin{funcdesc}{glNormalPointerx}{sequence}
Special Python version of \code{glNormalPointer} that uses \var{type}
\code{GL_FIXED} and \var{stride} 0.
\end{funcdesc}

\begin{funcdesc}{glReadPixels}{x, y, width, height, format, type}
The pixel data read is returned in a Python string.
\end{funcdesc}

\begin{funcdesc}{glTexCoordPointer}{size, type, stride, sequence}
Parameter \var{sequence} must be either a \class{gles.array} object or some other
Python sequence object. \class{gles.array} objects require less processing and
can be therefore slightly faster. If \class{gles.array} object is used, the
dimension and type of its data are ignored and \var{size} and \var{type} are
used instead.
\end{funcdesc}

\begin{funcdesc}{glTexCoordPointerb}{sequence}
Special Python version of \code{glTexCoordPointer} that accepts either a
\class{gles.array} object or some other Python sequence object. Other parameters
 of \code{glTexCoordPointer} will be determined as follows:
\begin{itemize}
\item \var{size} If \var{sequence} is an instance of \class{gles.array}, its dimension is used; otherwise the length of \var{sequence} is used.
\item \var{type} \code{GL_BYTE}
\item \var{stride} 0
\end{itemize}
\end{funcdesc}

\begin{funcdesc}{glTexCoordPointers}{sequence}
Special Python version of \code{glTexCoordPointer} that behaves exactly as
\code{glTexCoordPointerb} except \code{GL_SHORT} is used as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glTexCoordPointerf}{sequence}
Special Python version of \code{glTexCoordPointer} that behaves exactly as
\code{glTexCoordPointerb} except \code{GL_FLOAT} is used as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glTexCoordPointerx}{sequence}
Special Python version of \code{glTexCoordPointer} that behaves exactly as
\code{glTexCoordPointerb} except \code{GL_FIXED} is used as \var{type}.
\end{funcdesc}

\begin{funcdesc}{glTexEnvfv}{face, pname, params}
Parameter \var{params} must be a Python sequence containing float values.
\end{funcdesc}

\begin{funcdesc}{glTexEnvxv}{face, pname, params}
Parameter \var{params} must be a Python sequence containing integer values.
\end{funcdesc}

\begin{funcdesc}{glTexImage2D}{target, level, internalformat, width, height, border, format, type, pixels}
Parameter \var{pixels} must be either a Python string, a \class{gles.array}
object, or \class{graphics.Image} object. Python strings are taken as literal
data with no conversion. The dimension and type of data in \class{gles.array}
objects are ignored: the raw data in the array is used.

Use of \class{graphics.Image} objects is limited to only some combinations of
\var{format} and \var{type}. Table \ref{tab1} below shows the accepted
combinations. To get the best results and performance, the \class{CFbsBitmap}
object in the \class{graphics.Image} object should be in the equivalent display