GLCanvas.java revision 50b33abe053ccab7be3d1bca2328e792507963d4 
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
23//
24// GLCanvas gives a convenient interface to draw using OpenGL.
25//
26// When a rectangle is specified in this interface, it means the region
27// [x, x+width) * [y, y+height)
28//
29public interface GLCanvas {
30    public enum Blending {
31        Additive, Mix,
32    }
33
34    public GLId getGLId();
35
36    // Tells GLCanvas the size of the underlying GL surface. This should be
37    // called before first drawing and when the size of GL surface is changed.
38    // This is called by GLRoot and should not be called by the clients
39    // who only want to draw on the GLCanvas. Both width and height must be
40    // nonnegative.
41    public void setSize(int width, int height);
42
43    // Clear the drawing buffers. This should only be used by GLRoot.
44    public void clearBuffer();
45
46    public void clearBuffer(float[] argb);
47
48    // Sets and gets the current alpha, alpha must be in [0, 1].
49    public void setAlpha(float alpha);
50
51    public float getAlpha();
52
53    // (current alpha) = (current alpha) * alpha
54    public void multiplyAlpha(float alpha);
55
56    // Change the current transform matrix.
57    public void translate(float x, float y, float z);
58
59    public void translate(float x, float y);
60
61    public void scale(float sx, float sy, float sz);
62
63    public void rotate(float angle, float x, float y, float z);
64
65    public void multiplyMatrix(float[] mMatrix, int offset);
66
67    // Pushes the configuration state (matrix, and alpha) onto
68    // a private stack.
69    public void save();
70
71    // Same as save(), but only save those specified in saveFlags.
72    public void save(int saveFlags);
73
74    public static final int SAVE_FLAG_ALL = 0xFFFFFFFF;
75    public static final int SAVE_FLAG_ALPHA = 0x01;
76    public static final int SAVE_FLAG_MATRIX = 0x02;
77    public static final int SAVE_FLAG_BLEND = 0x04;
78
79    // Pops from the top of the stack as current configuration state (matrix,
80    // alpha, and clip). This call balances a previous call to save(), and is
81    // used to remove all modifications to the configuration state since the
82    // last save call.
83    public void restore();
84
85    // Draws a line using the specified paint from (x1, y1) to (x2, y2).
86    // (Both end points are included).
87    public void drawLine(float x1, float y1, float x2, float y2, GLPaint paint);
88
89    // Draws a rectangle using the specified paint from (x1, y1) to (x2, y2).
90    // (Both end points are included).
91    public void drawRect(float x1, float y1, float x2, float y2, GLPaint paint);
92
93    // Fills the specified rectangle with the specified color.
94    public void fillRect(float x, float y, float width, float height, int color);
95
96    // Draws a texture to the specified rectangle.
97    public void drawTexture(BasicTexture texture, int x, int y, int width, int height);
98
99    public void drawMesh(BasicTexture tex, int x, int y, int xyBuffer,
100            int uvBuffer, int indexBuffer, int indexCount);
101
102    // Draws the source rectangle part of the texture to the target rectangle.
103    public void drawTexture(BasicTexture texture, RectF source, RectF target);
104
105    // Draw a texture with a specified texture transform.
106    public void drawTexture(BasicTexture texture, float[] mTextureTransform,
107                int x, int y, int w, int h);
108
109    // Draw two textures to the specified rectangle. The actual texture used is
110    // from * (1 - ratio) + to * ratio
111    // The two textures must have the same size.
112    public void drawMixed(BasicTexture from, int toColor,
113            float ratio, int x, int y, int w, int h);
114
115    // Draw a region of a texture and a specified color to the specified
116    // rectangle. The actual color used is from * (1 - ratio) + to * ratio.
117    // The region of the texture is defined by parameter "src". The target
118    // rectangle is specified by parameter "target".
119    public void drawMixed(BasicTexture from, int toColor,
120            float ratio, RectF src, RectF target);
121
122    // Unloads the specified texture from the canvas. The resource allocated
123    // to draw the texture will be released. The specified texture will return
124    // to the unloaded state. This function should be called only from
125    // BasicTexture or its descendant
126    public boolean unloadTexture(BasicTexture texture);
127
128    // Delete the specified buffer object, similar to unloadTexture.
129    public void deleteBuffer(int bufferId);
130
131    // Delete the textures and buffers in GL side. This function should only be
132    // called in the GL thread.
133    public void deleteRecycledResources();
134
135    // Dump statistics information and clear the counters. For debug only.
136    public void dumpStatisticsAndClear();
137
138    public void beginRenderTarget(RawTexture texture);
139
140    public void endRenderTarget();
141
142    /**
143     * Sets texture parameters to use GL_CLAMP_TO_EDGE for both
144     * GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T. Sets texture parameters to be
145     * GL_LINEAR for GL_TEXTURE_MIN_FILTER and GL_TEXTURE_MAG_FILTER.
146     * bindTexture() must be called prior to this.
147     *
148     * @param texture The texture to set parameters on.
149     */
150    public void setTextureParameters(BasicTexture texture);
151
152    /**
153     * Initializes the texture to a size by calling texImage2D on it.
154     *
155     * @param texture The texture to initialize the size.
156     * @param format The texture format (e.g. GL_RGBA)
157     * @param type The texture type (e.g. GL_UNSIGNED_BYTE)
158     */
159    public void initializeTextureSize(BasicTexture texture, int format, int type);
160
161    /**
162     * Initializes the texture to a size by calling texImage2D on it.
163     *
164     * @param texture The texture to initialize the size.
165     * @param bitmap The bitmap to initialize the bitmap with.
166     */
167    public void initializeTexture(BasicTexture texture, Bitmap bitmap);
168
169    /**
170     * Calls glTexSubImage2D to upload a bitmap to the texture.
171     *
172     * @param texture The target texture to write to.
173     * @param xOffset Specifies a texel offset in the x direction within the
174     *            texture array.
175     * @param yOffset Specifies a texel offset in the y direction within the
176     *            texture array.
177     * @param format The texture format (e.g. GL_RGBA)
178     * @param type The texture type (e.g. GL_UNSIGNED_BYTE)
179     */
180    public void texSubImage2D(BasicTexture texture, int xOffset, int yOffset, 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 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 int uploadBuffer(java.nio.ByteBuffer buffer);
198
199    /**
200     * Sets the blending algorithm if a texture is not opaque.
201     *
202     * @param blending Either mixing (overlay) or adding a texture.
203     */
204    public void setBlending(Blending blending);
205
206    /**
207     * Enable stencil test
208     */
209    public void enableStencil();
210
211    /**
212     * Disable stencil.
213     */
214    public void disableStencil();
215
216    /**
217     * Clears the stencil so that a new stencil can be generated.
218     */
219    public void clearStencilBuffer();
220
221    /**
222     * Start/stop updating the stencil buffer.
223     *
224     * @param update True if the stencil should be updated, false otherwise.
225     */
226    public void updateStencil(boolean update);
227
228    /**
229     * Changes how the stencil buffer is used.
230     *
231     * @param onlyOutside If true, only the area outside the stencil can be
232     *            changed. If false, the area inside the stencil can be drawn to
233     *            as well.
234     */
235    public void drawOnlyOutsideStencil(boolean onlyOutside);
236
237    /**
238     * After LightCycle makes GL calls, this method is called to restore the GL
239     * configuration to the one expected by GLCanvas.
240     */
241    public void recoverFromLightCycle();
242
243    /**
244     * Gets the bounds given by x, y, width, and height as well as the internal
245     * matrix state. There is no special handling for non-90-degree rotations.
246     * It only considers the lower-left and upper-right corners as the bounds.
247     *
248     * @param bounds The output bounds to write to.
249     * @param x The left side of the input rectangle.
250     * @param y The bottom of the input rectangle.
251     * @param width The width of the input rectangle.
252     * @param height The height of the input rectangle.
253     */
254    public void getBounds(Rect bounds, int x, int y, int width, int height);
255}
256