OpenGL ES教程I之创建OpenGL视图(原文对照)

OpenGL ES Tutorial for Android – Part I – Setting up the view

December 3rd, 2009 by Per-Erik Bergman — Android, Embedded

 

I'm going to write a couple of tutorials on using OpenGL ES on Android phones. The theory of OpenGL ES is the same on different devices so it should be quite easy to convert them to another platform.

我将写一些关于在Andoird 手机上使用OpenGL Es的教程。理论上OpenGL ES适用于不同的设备（平台），因此很容易被移植到其它平台。

I can't always remember where I found particular info so I might not always be able to give you the right reference. If you feel that I have borrowed stuff from you but have forgotten to add you as a reference, please e-mail me.

我常常忘了我所搜集的资料的来源与出处，所以（在某些资料方面）我可能不能给出正确的引用。如果您觉得我使用了您的资料而没有标明引用（位置），请发电子邮件给我。

In the code examples I will have two different links for each function. The actual function will be linked to the android documentation and after that I will also link the OpenGL documentations. Like this:

在示例代码中，我对每个函数将使用两种不同的链接。点击函数将链接到Android doc（Android doc太简单了，建议还是链接到OpenGL doc吧），在函数后面，我会添加一个到OpenGL docs的链接，如下：

gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.

So, let's start.

好了，（言归正传）让我们这就开始OpenGL学习之旅吧。

In this tutorial I will show you how to set up your OpenGL ES view that’s always a good place to start.

在本教程中，我将（先）展示怎样来建立OpenGL ES界面，通常这是一个好的开始。

Setting up an OpenGL ES View

Setting up a OpenGL view has never been hard and on Android it is still easy. There really are only two things you need to get started.

在Android中建立一个OpenGL视图非常简单，您需要做的只有两件事。

GLSurfaceView

GLSurfaceView is a API class in Android 1.5 that helps you write OpenGL ES applications.

GLSurfaceView是Android1.5中帮助您编写OpenGL ES应用程序的API类（，其具有以下功能）

·         Providing the glue code to connect OpenGL ES to the View system.

·         Providing the glue code to make OpenGL ES work with the Activity life-cycle.

·         Making it easy to choose an appropriate frame buffer pixel format.

·         Creating and managing a separate rendering thread to enable smooth animation.

·         Providing easy-to-use debugging tools for tracing OpenGL ES API calls and checking for errors.

·         提供了OpenGL ES连接View系统的粘合代码。

·         提供了OpenGL ES与Activity生命周期协作的粘合代码。

·         易于选择合适的帧缓冲像素格式。

·         创建和管理独立的渲染线程来启用平滑动画（效果）

·         提供易于使用的调试工具来跟踪OpenGL ES API调用与检查错误。

If you want to get going fast with your OpenGL ES application this is where you should start.

The only function you need to call on is:

如果您想快速着手OpenGL ES应用程序，请从这里开始

您需要调用的唯一函数是：

public void  setRenderer(GLSurfaceView.Renderer renderer)

Read more at: GLSurfaceView

GLSurfaceView.Renderer

GLSurfaceView.Renderer is a generic render interface. In your implementation of this renderer you should put all your calls to render a frame.

GLSurfaceView.Renderer是一个通用的渲染接口，您必须实现此类的抽象方法来画（动画中的）帧
There are three functions to implement:

您需要实现的三个方法如下：

// Called when the surface is created or recreated.

// 当平面创建或或重新创建的时候调用

 

public void onSurfaceCreated(GL10 gl, EGLConfig config)

 

// Called to draw the current frame.

// 画当前帧

public void onDrawFrame(GL10 gl)

 

// Called when the surface changed size.

// 当视图大小变更的时候调用，如屏幕横纵切换

public void onSurfaceChanged(GL10 gl, int width, int height)

onSurfaceCreated

Here it's a good thing to setup things that you don't change so often in the rendering cycle. Stuff like what color to clear the screen with, enabling z-buffer and so on.

推荐将一些在渲染周期中不会变更的代码放到此处，如设置屏幕初始颜色，开始Z轴缓冲等。

onDrawFrame

Here is where the actual drawing take place.

在此函数中进行绘画（帧）

onSurfaceChanged

If your device supports flipping between landscape and portrait you will get a call to this function when it happens. What you do here is setting upp the new ratio.
Read more at: GLSurfaceView.Renderer

如果您的设备支持横竖屏切换，那么在切换发生时，您就需要在此方法中重新设置新的横纵比例了。

Putting it together

First we create our activity, we keep it clean and simple.

首先，创建一个尽可能的简洁 的Activity。

package se.jayway.opengl.tutorial;

 

import android.app.Activity;

import android.opengl.GLSurfaceView;

import android.os.Bundle;

 

public class TutorialPartI extends Activity {

    /** Called when the activity is first created. */

    @Override

    public void onCreate(Bundle savedInstanceState) {

            super.onCreate(savedInstanceState);

               GLSurfaceView view = new GLSurfaceView(this);

             view.setRenderer(new OpenGLRenderer());

             setContentView(view);

    }

}

Our renderer takes little bit more work to setup, look at it and I will explain the code a bit more.

更多的render设置，请见我扩展的renderer类

package se.jayway.opengl.tutorial;

 

import javax.microedition.khronos.egl.EGLConfig;

import javax.microedition.khronos.opengles.GL10;

 

import android.opengl.GLU;

import android.opengl.GLSurfaceView.Renderer;

 

public class OpenGLRenderer implements Renderer {

        /*

         * (non-Javadoc)

         *

         * @see

         * android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.

         * microedition.khronos.opengles.GL10, javax.microedition.khronos.

         * egl.EGLConfig)

         */

        public void onSurfaceCreated(GL10 gl, EGLConfig config) {

                // Set the background color to black ( rgba ).

                // 设置背景颜色为黑色 ( rgba ).

                gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.

                // Enable Smooth Shading, default not really needed.

                // 开启平滑阴影，实际上不需要（默认的shadeModel就是GL_SMOOTH）

                gl.glShadeModel(GL10.GL_SMOOTH);// OpenGL docs.

                // Depth buffer setup.

                // 设置深度缓冲

                gl.glClearDepthf(1.0f);// OpenGL docs.

                // Enables depth testing.

                // 启用深度测试

                gl.glEnable(GL10.GL_DEPTH_TEST);// OpenGL docs.

                // The type of depth testing to do.

                // 设置深度测试类型

                gl.glDepthFunc(GL10.GL_LEQUAL);// OpenGL docs.

                // Really nice perspective calculations.

                // 真实透视计算

                gl.glHint(GL10.GL_PERSPECTIVE_CORRECTION_HINT, // OpenGL docs.

                          GL10.GL_NICEST);

        }

 

        /*

         * (non-Javadoc)

         *

         * @see

         * android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.

         * microedition.khronos.opengles.GL10)

         */

        public void onDrawFrame(GL10 gl) {

                // Clears the screen and depth buffer.

                // 清除屏幕和深度（Z轴）缓冲

                gl.glClear(GL10.GL_COLOR_BUFFER_BIT | // OpenGL docs.

                           GL10.GL_DEPTH_BUFFER_BIT);

        }

 

        /*

         * (non-Javadoc)

         *

         * @see

         * android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.

         * microedition.khronos.opengles.GL10, int, int)

         */

        public void onSurfaceChanged(GL10 gl, int width, int height) {

                // Sets the current view port to the new size.

                //设置当前视窗新大小

                gl.glViewport(0, 0, width, height);// OpenGL docs.

                // Select the projection matrix

                // 选择投影方式为透视投影

                gl.glMatrixMode(GL10.GL_PROJECTION);// OpenGL docs.

                // Reset the projection matrix

                // 重置投影矩阵

                gl.glLoadIdentity();// OpenGL docs.

                // Calculate the aspect ratio of the window

                // 计算窗口视角比例

                GLU.gluPerspective(gl, 45.0f,

                                   (float) width / (float) height,

                                   0.1f, 100.0f);

                // Select the modelview matrix

                // 选择变换方式为modelview

                gl.glMatrixMode(GL10.GL_MODELVIEW);// OpenGL docs.

                // Reset the modelview matrix

                // 重置变换矩阵

                gl.glLoadIdentity();// OpenGL docs.

        }

}

Fullscreen

Just add this lines in the OpenGLDemo class and you will get fullscreen.

只需要在OpenGLDemo类中添加如下代码，就可以让Activity全屏。建议还是在Manifest.xml中配置全屏

    public void onCreate(Bundle savedInstanceState) {

        super.onCreate(savedInstanceState);

        this.requestWindowFeature(Window.FEATURE_NO_TITLE); // (NEW)

        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,

            WindowManager.LayoutParams.FLAG_FULLSCREEN); // (NEW)

        ... // Previous code.

    }

This is pretty much all you need to get your view up and running. If you compile and run it you will see a nice black screen.

如果想要运行创建的OpenGL视图，以上就已经足够了，编译运行此应用，你可以看到一个纯黑色的屏幕。不过GLSurfaceView运行于独立的线程，所以需要将此线程同步到Android主线程中，做法是在Activity pause时，GLSurfaceView也pause；Activity resume时，GLSurfaceView线程也resume

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_I.zip
You can also checkout the code from: code.google.com

Next tutorial: OpenGL ES Tutorial for Android – Part II – Building a polygon

Per-Erik Bergman
Consultant at Jayway