GLCanvas.java revision bdb71cc6acbd78d5aa02d2e142b792247fb6e0bd 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.gallery3d.glrenderer;
18
19import android.graphics.Bitmap;
20import android.graphics.Rect;
21import android.graphics.RectF;
22
23import javax.microedition.khronos.opengles.GL11;
24
25//
26// GLCanvas gives a convenient interface to draw using OpenGL.
27//
28// When a rectangle is specified in this interface, it means the region
29// [x, x+width) * [y, y+height)
30//
31public interface GLCanvas {
32
33    public GLId getGLId();
34
35    // Tells GLCanvas the size of the underlying GL surface. This should be
36    // called before first drawing and when the size of GL surface is changed.
37    // This is called by GLRoot and should not be called by the clients
38    // who only want to draw on the GLCanvas. Both width and height must be
39    // nonnegative.
40    public abstract void setSize(int width, int height);
41
42    // Clear the drawing buffers. This should only be used by GLRoot.
43    public abstract void clearBuffer();
44
45    public abstract void clearBuffer(float[] argb);
46
47    // Sets and gets the current alpha, alpha must be in [0, 1].
48    public abstract void setAlpha(float alpha);
49
50    public abstract float getAlpha();
51
52    // (current alpha) = (current alpha) * alpha
53    public abstract void multiplyAlpha(float alpha);
54
55    // Change the current transform matrix.
56    public abstract void translate(float x, float y, float z);
57
58    public abstract void translate(float x, float y);
59
60    public abstract void scale(float sx, float sy, float sz);
61
62    public abstract void rotate(float angle, float x, float y, float z);
63
64    public abstract void multiplyMatrix(float[] mMatrix, int offset);
65
66    // Pushes the configuration state (matrix, and alpha) onto
67    // a private stack.
68    public abstract void save();
69
70    // Same as save(), but only save those specified in saveFlags.
71    public abstract void save(int saveFlags);
72
73    public static final int SAVE_FLAG_ALL = 0xFFFFFFFF;
74    public static final int SAVE_FLAG_ALPHA = 0x01;
75    public static final int SAVE_FLAG_MATRIX = 0x02;
76
77    // Pops from the top of the stack as current configuration state (matrix,
78    // alpha, and clip). This call balances a previous call to save(), and is
79    // used to remove all modifications to the configuration state since the
80    // last save call.
81    public abstract void restore();
82
83    // Draws a line using the specified paint from (x1, y1) to (x2, y2).
84    // (Both end points are included).
85    public abstract void drawLine(float x1, float y1, float x2, float y2, GLPaint paint);
86
87    // Draws a rectangle using the specified paint from (x1, y1) to (x2, y2).
88    // (Both end points are included).
89    public abstract void drawRect(float x1, float y1, float x2, float y2, GLPaint paint);
90
91    // Fills the specified rectangle with the specified color.
92    public abstract void fillRect(float x, float y, float width, float height, int color);
93
94    // Draws a texture to the specified rectangle.
95    public abstract void drawTexture(
96            BasicTexture texture, int x, int y, int width, int height);
97
98    public abstract void drawMesh(BasicTexture tex, int x, int y, int xyBuffer,
99            int uvBuffer, int indexBuffer, int indexCount);
100
101    // Draws the source rectangle part of the texture to the target rectangle.
102    public abstract void drawTexture(BasicTexture texture, RectF source, RectF target);
103
104    // Draw a texture with a specified texture transform.
105    public abstract void drawTexture(BasicTexture texture, float[] mTextureTransform,
106                int x, int y, int w, int h);
107
108    // Draw two textures to the specified rectangle. The actual texture used is
109    // from * (1 - ratio) + to * ratio
110    // The two textures must have the same size.
111    public abstract void drawMixed(BasicTexture from, int toColor,
112            float ratio, int x, int y, int w, int h);
113
114    // Draw a region of a texture and a specified color to the specified
115    // rectangle. The actual color used is from * (1 - ratio) + to * ratio.
116    // The region of the texture is defined by parameter "src". The target
117    // rectangle is specified by parameter "target".
118    public abstract void drawMixed(BasicTexture from, int toColor,
119            float ratio, RectF src, RectF target);
120
121    // Unloads the specified texture from the canvas. The resource allocated
122    // to draw the texture will be released. The specified texture will return
123    // to the unloaded state. This function should be called only from
124    // BasicTexture or its descendant
125    public abstract boolean unloadTexture(BasicTexture texture);
126
127    // Delete the specified buffer object, similar to unloadTexture.
128    public abstract void deleteBuffer(int bufferId);
129
130    // Delete the textures and buffers in GL side. This function should only be
131    // called in the GL thread.
132    public abstract void deleteRecycledResources();
133
134    // Dump statistics information and clear the counters. For debug only.
135    public abstract void dumpStatisticsAndClear();
136
137    public abstract void beginRenderTarget(RawTexture texture);
138
139    public abstract void endRenderTarget();
140
141    /**
142     * Sets texture parameters to use GL_CLAMP_TO_EDGE for both
143     * GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T. Sets texture parameters to be
144     * GL_LINEAR for GL_TEXTURE_MIN_FILTER and GL_TEXTURE_MAG_FILTER.
145     * bindTexture() must be called prior to this.
146     *
147     * @param texture The texture to set parameters on.
148     */
149    public abstract void setTextureParameters(BasicTexture texture);
150
151    /**
152     * Initializes the texture to a size by calling texImage2D on it.
153     *
154     * @param texture The texture to initialize the size.
155     * @param format The texture format (e.g. GL_RGBA)
156     * @param type The texture type (e.g. GL_UNSIGNED_BYTE)
157     */
158    public abstract void initializeTextureSize(BasicTexture texture, int format, int type);
159
160    /**
161     * Initializes the texture to a size by calling texImage2D on it.
162     *
163     * @param texture The texture to initialize the size.
164     * @param bitmap The bitmap to initialize the bitmap with.
165     */
166    public abstract void initializeTexture(BasicTexture texture, Bitmap bitmap);
167
168    /**
169     * Calls glTexSubImage2D to upload a bitmap to the texture.
170     *
171     * @param texture The target texture to write to.
172     * @param xOffset Specifies a texel offset in the x direction within the
173     *            texture array.
174     * @param yOffset Specifies a texel offset in the y direction within the
175     *            texture array.
176     * @param format The texture format (e.g. GL_RGBA)
177     * @param type The texture type (e.g. GL_UNSIGNED_BYTE)
178     */
179    public abstract void texSubImage2D(BasicTexture texture, int xOffset, int yOffset,
180            Bitmap bitmap,
181            int format, int type);
182
183    /**
184     * Generates buffers and uploads the buffer data.
185     *
186     * @param buffer The buffer to upload
187     * @return The buffer ID that was generated.
188     */
189    public abstract int uploadBuffer(java.nio.FloatBuffer buffer);
190
191    /**
192     * Generates buffers and uploads the element array buffer data.
193     *
194     * @param buffer The buffer to upload
195     * @return The buffer ID that was generated.
196     */
197    public abstract int uploadBuffer(java.nio.ByteBuffer buffer);
198
199    /**
200     * Enable stencil test
201     */
202    public abstract void enableStencil();
203
204    /**
205     * Disable stencil.
206     */
207    public abstract void disableStencil();
208
209    /**
210     * Clears the stencil so that a new stencil can be generated.
211     */
212    public abstract void clearStencilBuffer();
213
214    /**
215     * Start/stop updating the stencil buffer.
216     *
217     * @param update True if the stencil should be updated, false otherwise.
218     */
219    public abstract void updateStencil(boolean update);
220
221    /**
222     * Changes how the stencil buffer is used.
223     *
224     * @param onlyOutside If true, only the area outside the stencil can be
225     *            changed. If false, the area inside the stencil can be drawn to
226     *            as well.
227     */
228    public abstract void drawOnlyOutsideStencil(boolean onlyOutside);
229
230    /**
231     * After LightCycle makes GL calls, this method is called to restore the GL
232     * configuration to the one expected by GLCanvas.
233     */
234    public abstract void recoverFromLightCycle();
235
236    /**
237     * Gets the bounds given by x, y, width, and height as well as the internal
238     * matrix state. There is no special handling for non-90-degree rotations.
239     * It only considers the lower-left and upper-right corners as the bounds.
240     *
241     * @param bounds The output bounds to write to.
242     * @param x The left side of the input rectangle.
243     * @param y The bottom of the input rectangle.
244     * @param width The width of the input rectangle.
245     * @param height The height of the input rectangle.
246     */
247    public abstract void getBounds(Rect bounds, int x, int y, int width, int height);
248}
249