index.jd revision b10b48f62d3cac684424e4181d4e8ec61f227e95
1page.title=Graphics 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li><a href="#options">Consider your Options</a></li> 9 <li><a href="#draw-to-view">Simple Graphics Inside a View</a></li> 10 <li><a href="#draw-with-canvas">Draw with a Canvas</a> 11 <ol> 12 <li><a href="#on-view">On a View</a></li> 13 <li><a href="#on-surfaceview">On a SurfaceView</a></li> 14 </ol> 15 </li> 16 </ol> 17 <h2>See also</h2> 18 <ol> 19 <li><a href="{@docRoot}guide/topics/graphics/opengl.html">3D with OpenGL</a></li> 20 <li><a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a></li> 21 </ol> 22 </div> 23</div> 24 25<p>Android graphics are powered by a custom 2D graphics library, and the framework provides 26support for high performance 3D graphics in the form of OpenGL ES and RenderScript. The most 27common 2D graphics APIs can be found in the {@link android.graphics.drawable drawable package}. 28OpenGL APIs are available from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES} and 29the {@link android.opengl} packages. The RenderScript APIs are available in the 30{@link android.renderscript} package.</p> 31 32<p>When starting a project, it's important to consider exactly what your graphical demands will be. 33Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations 34for a rather static application should be implemented much differently than graphics and animations 35for an interactive game or 3D rendering.</p> 36 37<p>Here, we'll discuss a few of the options you have for drawing graphics on Android, 38and which tasks they're best suited for.</p> 39 40<p>If you're specifically looking for information on drawing 3D graphics, this page won't 41help a lot. However, the information below about how to <a href="#draw-with-canvas">Draw with a 42Canvas</a> (and the section on SurfaceView), will give you a quick idea of how you should draw to 43the View hierarchy. For more information on Android's 3D graphics APIs, see 44the <a href="opengl.html">3D with OpenGL</a> and 45<a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> documents.</p> 46 47 48<h2 id="options">Consider your Options</h2> 49 50<p>When drawing 2D graphics, you'll typically do so in one of two ways:</p> 51<ol type="a"> 52 <li>Draw your graphics or animations into a View object from your layout. In this manner, 53 the drawing (and any animation) of your graphics is handled by the system's 54 normal View hierarchy drawing process — you simply define the graphics to go inside the View.</li> 55 <li>Draw your graphics directly to a Canvas. This way, you personally call the appropriate class's 56 <code>draw()</code> method (passing it your Canvas), or one of the Canvas <code>draw...()</code> methods (like 57 <code>{@link android.graphics.Canvas#drawPicture(Picture,Rect) drawPicture()}</code>). In doing so, you are also in 58 control of any animation.</li> 59</ol> 60 61<p>Option "a," drawing to a View, is your best choice when you want to draw simple graphics that do not 62need to change dynamically and are not part of a performance-intensive game. For example, you should 63draw your graphics into a View when you want to display a static graphic or predefined animation, within 64an otherwise static application. Read <a href="#draw-to-view">Simple Graphics Inside a View</a>.</li> 65 66<p>Option "b," drawing to a Canvas, is better when your application needs to regularly re-draw itself. 67Basically, any video game should be drawing to the Canvas on its own. However, there's more than 68one way to do this: </p> 69<ul> 70 <li>In the same thread as your UI Activity, wherein you create a custom View component in 71 your layout, call <code>{@link android.view.View#invalidate()}</code> and then handle the 72 <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback..</li> 73 <li>Or, in a separate thread, wherein you manage a {@link android.view.SurfaceView} and 74 perform draws to the Canvas as fast as your thread is capable 75 (you do not need to request <code>invalidate()</code>).</li> 76</ul> 77<p>...Begin by reading <a href="#draw-with-canvas">Draw with a Canvas</a>.</p> 78 79<h2 id="draw-to-view">Simple Graphics Inside a View</h2> 80 81<p>If you'll be drawing some simple graphics (images, shapes, colors, pre-defined animations, etc.), 82then you should probably just draw to the background of a View or 83to the content of an {@link android.widget.ImageView} in your layout. 84In this case, you can skip the rest of this document and learn how to 85draw graphics and animations in the <a href="2d-graphics.html">2D Graphics</a> document. 86</p> 87 88 89<h2 id="draw-with-canvas">Draw with a Canvas</h2> 90 91<p>When you're writing an application in which you would like to perform specialized drawing 92and/or control the animation of graphics, 93you should do so by drawing through a {@link android.graphics.Canvas}. A Canvas works for you as 94a pretense, or interface, to the actual surface upon which your graphics will be drawn — it 95holds all of your "draw" calls. Via the Canvas, your drawing is actually performed upon an 96underlying {@link android.graphics.Bitmap}, which is placed into the window.</p> 97 98<p>In the event that you're drawing within the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> 99callback method, the Canvas is provided for you and you need only place your drawing calls upon it. 100You can also acquire a Canvas from <code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code>, 101when dealing with a SurfaceView object. (Both of these scenarios are discussed in the following sections.) 102However, if you need to create a new Canvas, then you must define the {@link android.graphics.Bitmap} 103upon which drawing will actually be performed. The Bitmap is always required for a Canvas. You can set up 104a new Canvas like this:</p> 105<pre> 106Bitmap b = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888); 107Canvas c = new Canvas(b); 108</pre> 109 110<p>Now your Canvas will draw onto the defined Bitmap. After drawing upon it with the Canvas, you can then carry your 111Bitmap to another Canvas with one of the <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Matrix,Paint) 112Canvas.drawBitmap(Bitmap,...)}</code> methods. It's recommended that you ultimately draw your final 113graphics through a Canvas offered to you 114by <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code> or 115<code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code> (see the following sections).</p> 116 117<p>The {@link android.graphics.Canvas} class has its own set of drawing methods that you can use, 118like <code>drawBitmap(...)</code>, <code>drawRect(...)</code>, <code>drawText(...)</code>, and many more. 119Other classes that you might use also have <code>draw()</code> methods. For example, you'll probably 120have some {@link android.graphics.drawable.Drawable} objects that you want to put on the Canvas. Drawable 121has its own <code>{@link android.graphics.drawable.Drawable#draw(Canvas) draw()}</code> method 122that takes your Canvas as an argument.</p> 123 124 125<h3 id="on-view">On a View</h3> 126 127<p>If your application does not require a significant amount of processing or 128frame-rate speed (perhaps for a chess game, a snake game, 129or another slowly-animated application), then you should consider creating a custom View component 130and drawing with a Canvas in <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code>. 131The most convenient aspect of doing so is that the Android framework will 132provide you with a pre-defined Canvas to which you will place your drawing calls.</p> 133 134<p>To start, extend the {@link android.view.View} class (or descendant thereof) and define 135the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback method. This method will be called by the Android 136framework to request that your View draw itself. This is where you will perform all your calls 137to draw through the {@link android.graphics.Canvas}, which is passed to you through the <code>onDraw()</code> callback.</p> 138 139<p>The Android framework will only call <code>onDraw()</code> as necessary. Each time that 140your application is prepared to be drawn, you must request your View be invalidated by calling 141<code>{@link android.view.View#invalidate()}</code>. This indicates that you'd like your View to be drawn and 142Android will then call your <code>onDraw()</code> method (though is not guaranteed that the callback will 143be instantaneous). </p> 144 145<p>Inside your View component's <code>onDraw()</code>, use the Canvas given to you for all your drawing, 146using various <code>Canvas.draw...()</code> methods, or other class <code>draw()</code> methods that 147take your Canvas as an argument. Once your <code>onDraw()</code> is complete, the Android framework will 148use your Canvas to draw a Bitmap handled by the system.</p> 149 150<p class="note"><strong>Note: </strong> In order to request an invalidate from a thread other than your main 151Activity's thread, you must call <code>{@link android.view.View#postInvalidate()}</code>.</p> 152 153<p>Also read <a href="{@docRoot}guide/topics/ui/custom-components.html">Custom Components</a> 154for a guide to extending a View class, and <a href="2d-graphics.html">2D Graphics: Drawables</a> for 155information on using Drawable objects like images from your resources and other primitive shapes.</p> 156 157<p>For a sample application, see the Snake game, in the SDK samples folder: 158<code><your-sdk-directory>/samples/Snake/</code>.</p> 159 160<h3 id="on-surfaceview">On a SurfaceView</h3> 161 162<p>The {@link android.view.SurfaceView} is a special subclass of View that offers a dedicated 163drawing surface within the View hierarchy. The aim is to offer this drawing surface to 164an application's secondary thread, so that the application isn't required 165to wait until the system's View hierarchy is ready to draw. Instead, a secondary thread 166that has reference to a SurfaceView can draw to its own Canvas at its own pace.</p> 167 168<p>To begin, you need to create a new class that extends {@link android.view.SurfaceView}. The class should also 169implement {@link android.view.SurfaceHolder.Callback}. This subclass is an interface that will notify you 170with information about the underlying {@link android.view.Surface}, such as when it is created, changed, or destroyed. 171These events are important so that you know when you can start drawing, whether you need 172to make adjustments based on new surface properties, and when to stop drawing and potentially 173kill some tasks. Inside your SurfaceView class is also a good place to define your secondary Thread class, which will 174perform all the drawing procedures to your Canvas.</p> 175 176<p>Instead of handling the Surface object directly, you should handle it via 177a {@link android.view.SurfaceHolder}. So, when your SurfaceView is initialized, get the SurfaceHolder by calling 178<code>{@link android.view.SurfaceView#getHolder()}</code>. You should then notify the SurfaceHolder that you'd 179like to receive SurfaceHolder callbacks (from {@link android.view.SurfaceHolder.Callback}) by calling 180{@link android.view.SurfaceHolder#addCallback(SurfaceHolder.Callback) addCallback()} 181(pass it <var>this</var>). Then override each of the 182{@link android.view.SurfaceHolder.Callback} methods inside your SurfaceView class.</p> 183 184<p>In order to draw to the Surface Canvas from within your second thread, you must pass the thread your SurfaceHandler 185and retrieve the Canvas with <code>{@link android.view.SurfaceHolder#lockCanvas() lockCanvas()}</code>. 186You can now take the Canvas given to you by the SurfaceHolder and do your necessary drawing upon it. 187Once you're done drawing with the Canvas, call 188<code>{@link android.view.SurfaceHolder#unlockCanvasAndPost(Canvas) unlockCanvasAndPost()}</code>, passing it 189your Canvas object. The Surface will now draw the Canvas as you left it. Perform this sequence of locking and 190unlocking the canvas each time you want to redraw.</p> 191 192<p class="note"><strong>Note:</strong> On each pass you retrieve the Canvas from the SurfaceHolder, 193the previous state of the Canvas will be retained. In order to properly animate your graphics, you must re-paint the 194entire surface. For example, you can clear the previous state of the Canvas by filling in a color 195with <code>{@link android.graphics.Canvas#drawColor(int) drawColor()}</code> or setting a background image 196with <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Rect,RectF,Paint) drawBitmap()}</code>. Otherwise, 197you will see traces of the drawings you previously performed.</p> 198 199 200<p>For a sample application, see the Lunar Lander game, in the SDK samples folder: 201<code><your-sdk-directory>/samples/LunarLander/</code>. Or, 202browse the source in the <a href="{@docRoot}guide/samples/index.html">Sample Code</a> section.</p> 203 204 205 206 207 208 209 210 211