tobi/M7350
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

M7350v1_en_gpl

Browse Source
This commit is contained in:
T
2024-09-09 08:52:07 +00:00
commit f9cc65cfda
65988 changed files with 26357421 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
base/docs/html/guide/topics/graphics/2d-graphics.jd
+499
View File
@@ -0,0 +1,499 @@
page.title=2D Graphics
parent.title=2D and 3D Graphics
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#drawables">Drawables</a>
<ol>
<li><a href="#drawables-from-images">Creating from resource images</a></li>
<li><a href="#drawables-from-xml">Creating from resource XML</a></li>
</ol>
</li>
<li><a href="#shape-drawable">Shape Drawable</a></li>
<!-- <li><a href="#state-list">StateListDrawable</a></li> -->
<li><a href="#nine-patch">Nine-patch</a></li>
<li><a href="#tween-animation">Tween Animation</a></li>
<li><a href="#frame-animation">Frame Animation</a></li>
</ol>
</div>
</div>
<p>Android offers a custom 2D graphics library for drawing and animating shapes and images.
The {@link android.graphics.drawable} and {@link android.view.animation}
packages are where you'll find the common classes used for drawing and animating in two-dimensions.
</p>
<p>This document offers an introduction to drawing graphics in your Android application.
We'll discuss the basics of using Drawable objects to draw
graphics, how to use a couple subclasses of the Drawable class, and how to
create animations that either tween (move, stretch, rotate) a single graphic
or animate a series of graphics (like a roll of film).</p>
<h2 id="drawables">Drawables</h2>
<p>A {@link android.graphics.drawable.Drawable} is a general abstraction for "something that can be drawn."
You'll discover that the Drawable class extends to define a variety of specific kinds of drawable graphics,
including {@link android.graphics.drawable.BitmapDrawable}, {@link android.graphics.drawable.ShapeDrawable},
{@link android.graphics.drawable.PictureDrawable}, {@link android.graphics.drawable.LayerDrawable}, and several more.
Of course, you can also extend these to define your own custom Drawable objects that behave in unique ways.</p>
<p>There are three ways to define and instantiate a Drawable: using an image saved in your project resources;
using an XML file that defines the Drawable properties; or using the normal class constructors. Below, we'll discuss
each the first two techniques (using constructors is nothing new for an experienced developer).</p>
<h3 id="drawables-from-images">Creating from resource images</h3>
<p>A simple way to add graphics to your application is by referencing an image file from your project resources.
Supported file types are PNG (preferred), JPG (acceptable) and GIF (discouraged). This technique would
obviously be preferred for application icons, logos, or other graphics such as those used in a game.</p>
<p>To use an image resource, just add your file to the <code>res/drawable/</code> directory of your project.
From there, you can reference it from your code or your XML layout.
Either way, it is referred using a resource ID, which is the file name without the file type
extension (E.g., <code>my_image.png</code> is referenced as <var>my_image</var>).</p>
<p class="note"><strong>Note:</strong> Image resources placed in <code>res/drawable/</code> may be
automatically optimized with lossless image compression by the
<a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG that does
not require more than 256 colors may be converted to an 8-bit PNG with a color palette. This
will result in an image of equal quality but which requires less memory. So be aware that the
image binaries placed in this directory can change during the build. If you plan on reading
an image as a bit stream in order to convert it to a bitmap, put your images in the <code>res/raw/</code>
folder instead, where they will not be optimized.</p>
<h4>Example code</h4>
<p>The following code snippet demonstrates how to build an {@link android.widget.ImageView} that uses an image
from drawable resources and add it to the layout.</p>
<pre>
LinearLayout mLinearLayout;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Create a LinearLayout in which to add the ImageView
mLinearLayout = new LinearLayout(this);
// Instantiate an ImageView and define its properties
ImageView i = new ImageView(this);
i.setImageResource(R.drawable.my_image);
i.setAdjustViewBounds(true); // set the ImageView bounds to match the Drawable's dimensions
i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT));
// Add the ImageView to the layout and set the layout as the content view
mLinearLayout.addView(i);
setContentView(mLinearLayout);
}
</pre>
<p>In other cases, you may want to handle your image resource as a
{@link android.graphics.drawable.Drawable} object.
To do so, create a Drawable from the resource like so:
<pre>
Resources res = mContext.getResources();
Drawable myImage = res.getDrawable(R.drawable.my_image);
</pre>
<p class="warning"><strong>Note:</strong> Each unique resource in your project can maintain only one
state, no matter how many different objects you may instantiate for it. For example, if you instantiate two
Drawable objects from the same image resource, then change a property (such as the alpha) for one of the
Drawables, then it will also affect the other. So when dealing with multiple instances of an image resource,
instead of directly transforming the Drawable, you should perform a <a href="#tween-animation">tween animation</a>.</p>
<h4>Example XML</h4>
<p>The XML snippet below shows how to add a resource Drawable to an
{@link android.widget.ImageView} in the XML layout (with some red tint just for fun).
<pre>
&lt;ImageView
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:tint="#55ff0000"
android:src="@drawable/my_image"/>
</pre>
<p>For more information on using project resources, read about
<a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</p>
<h3 id="drawables-from-xml">Creating from resource XML</h3>
<p>By now, you should be familiar with Android's principles of developing a
<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>. Hence, you understand the power
and flexibility inherent in defining objects in XML. This philosophy caries over from Views to Drawables.
If there is a Drawable object that you'd like to create, which is not initially dependent on variables defined by
your application code or user interaction, then defining the Drawable in XML is a good option.
Even if you expect your Drawable to change its properties during the user's experience with your application,
you should consider defining the object in XML, as you can always modify properties once it is instantiated.</p>
<p>Once you've defined your Drawable in XML, save the file in the <code>res/drawable/</code> directory of
your project. Then, retrieve and instantiate the object by calling
{@link android.content.res.Resources#getDrawable(int) Resources.getDrawable()}, passing it the resource ID
of your XML file. (See the <a href="#drawable-xml-example">example below</a>.)</p>
<p>Any Drawable subclass that supports the <code>inflate()</code> method can be defined in
XML and instantiated by your application.
Each Drawable that supports XML inflation utilizes specific XML attributes that help define the object
properties (see the class reference to see what these are). See the class documentation for each
Drawable subclass for information on how to define it in XML.
<h4 id="drawable-xml-example">Example</h4>
<p>Here's some XML that defines a TransitionDrawable:</p>
<pre>
&lt;transition xmlns:android="http://schemas.android.com/apk/res/android">
&lt;item android:drawable="&#64;drawable/image_expand">
&lt;item android:drawable="&#64;drawable/image_collapse">
&lt;/transition>
</pre>
<p>With this XML saved in the file <code>res/drawable/expand_collapse.xml</code>,
the following code will instantiate the TransitionDrawable and set it as the content of an ImageView:</p>
<pre>
Resources res = mContext.getResources();
TransitionDrawable transition = (TransitionDrawable) res.getDrawable(R.drawable.expand_collapse);
ImageView image = (ImageView) findViewById(R.id.toggle_image);
image.setImageDrawable(transition);
</pre>
<p>Then this transition can be run forward (for 1 second) with:</p>
<pre>transition.startTransition(1000);</pre>
<p>Refer to the Drawable classes listed above for more information on the XML attributes supported by each.</p>
<h2 id="shape-drawable">Shape Drawable</h2>
<p>When you want to dynamically draw some two-dimensional graphics, a {@link android.graphics.drawable.ShapeDrawable}
object will probably suit your needs. With a ShapeDrawable, you can programmatically draw
primitive shapes and style them in any way imaginable.</p>
<p>A ShapeDrawable is an extension of {@link android.graphics.drawable.Drawable}, so you can use one where ever
a Drawable is expected &mdash; perhaps for the background of a View, set with
{@link android.view.View#setBackgroundDrawable(android.graphics.drawable.Drawable) setBackgroundDrawable()}.
Of course, you can also draw your shape as its own custom {@link android.view.View},
to be added to your layout however you please.
Because the ShapeDrawable has its own <code>draw()</code> method, you can create a subclass of View that
draws the ShapeDrawable during the <code>View.onDraw()</code> method.
Here's a basic extension of the View class that does just this, to draw a ShapeDrawable as a View:</p>
<pre>
public class CustomDrawableView extends View {
private ShapeDrawable mDrawable;
public CustomDrawableView(Context context) {
super(context);
int x = 10;
int y = 10;
int width = 300;
int height = 50;
mDrawable = new ShapeDrawable(new OvalShape());
mDrawable.getPaint().setColor(0xff74AC23);
mDrawable.setBounds(x, y, x + width, y + height);
}
protected void onDraw(Canvas canvas) {
mDrawable.draw(canvas);
}
}
</pre>
<p>In the constructor, a ShapeDrawable is defines as an {@link android.graphics.drawable.shapes.OvalShape}.
It's then given a color and the bounds of the shape are set. If you do not set the bounds, then the
shape will not be drawn, whereas if you don't set the color, it will default to black.</p>
<p>With the custom View defined, it can be drawn any way you like. With the sample above, we can
draw the shape programmatically in an Activity:</p>
<pre>
CustomDrawableView mCustomDrawableView;
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
mCustomDrawableView = new CustomDrawableView(this);
setContentView(mCustomDrawableView);
}
</pre>
<p>If you'd like to draw this custom drawable from the XML layout instead of from the Activity,
then the CustomDrawable class must override the {@link android.view.View#View(android.content.Context, android.util.AttributeSet) View(Context, AttributeSet)} constructor, which is called when
instantiating a View via inflation from XML. Then add a CustomDrawable element to the XML,
like so:</p>
<pre>
&lt;com.example.shapedrawable.CustomDrawableView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
/>
</pre>
<p>The ShapeDrawable class (like many other Drawable types in the {@link android.graphics.drawable} package)
allows you to define various properties of the drawable with public methods.
Some properties you might want to adjust include
alpha transparency, color filter, dither, opacity and color.</p>
<p>You can also define primitive drawable shapes using XML. For more information, see the
section about Shape Drawables in the <a
href="{@docRoot}guide/topics/resources/drawable-resource.html#Shape">Drawable Resources</a>
document.</p>
<!-- TODO
<h2 id="state-list">StateListDrawable</h2>
<p>A StateListDrawable is an extension of the DrawableContainer class, making it little different.
The primary distinction is that the
StateListDrawable manages a collection of images for the Drawable, instead of just one.
This means that it can switch the image when you want, without switching objects. However, the
intention of the StateListDrawable is to automatically change the image used based on the state
of the object it's attached to.
-->
<h2 id="nine-patch">Nine-patch</h2>
<p>A {@link android.graphics.drawable.NinePatchDrawable} graphic is a stretchable bitmap image, which Android
will automatically resize to accommodate the contents of the View in which you have placed it as the background.
An example use of a NinePatch is the backgrounds used by standard Android buttons &mdash;
buttons must stretch to accommodate strings of various lengths. A NinePatch drawable is a standard PNG
image that includes an extra 1-pixel-wide border. It must be saved with the extension <code>.9.png</code>,
and saved into the <code>res/drawable/</code> directory of your project.
</p>
<p>
The border is used to define the stretchable and static areas of
the image. You indicate a stretchable section by drawing one (or more) 1-pixel-wide
black line(s) in the left and top part of the border. (You can have as
many stretchable sections as you want.) The relative size of the stretchable
sections stays the same, so the largest sections always remain the largest.
</p>
<p>
You can also define an optional drawable section of the image (effectively,
the padding lines) by drawing a line on the right and bottom lines.
If a View object sets the NinePatch as its background and then specifies the
View's text, it will stretch itself so that all the text fits inside only
the area designated by the right and bottom lines (if included). If the
padding lines are not included, Android uses the left and top lines to
define this drawable area.
</p>
<p>To clarify the difference between the different lines, the left and top lines define
which pixels of the image are allowed to be replicated in order to stretch the image.
The bottom and right lines define the relative area within the image that the contents
of the View are allowed to lie within.</p>
<p>
Here is a sample NinePatch file used to define a button:
</p>
<img src="{@docRoot}images/ninepatch_raw.png" alt="" />
<p>This NinePatch defines one stretchable area with the left and top lines
and the drawable area with the bottom and right lines. In the top image, the dotted grey
lines identify the regions of the image that will be replicated in order to stretch the image. The pink
rectangle in the bottom image identifies the region in which the contents of the View are allowed.
If the contents don't fit in this region, then the image will be stretched so that they do.
</p>
<p>The <a href="{@docRoot}guide/developing/tools/draw9patch.html">Draw 9-patch</a> tool offers
an extremely handy way to create your NinePatch images, using a WYSIWYG graphics editor. It
even raises warnings if the region you've defined for the stretchable area is at risk of
producing drawing artifacts as a result of the pixel replication.
</p>
<h3>Example XML</h3>
<p>Here's some sample layout XML that demonstrates how to add a NinePatch image to a
couple of buttons. (The NinePatch image is saved as <code>res/drawable/my_button_background.9.png</code>
<pre>
&lt;Button id="@+id/tiny"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentTop="true"
android:layout_centerInParent="true"
android:text="Tiny"
android:textSize="8sp"
android:background="@drawable/my_button_background"/&gt;
&lt;Button id="@+id/big"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentBottom="true"
android:layout_centerInParent="true"
android:text="Biiiiiiig text!"
android:textSize="30sp"
android:background="@drawable/my_button_background"/&gt;
</pre>
<p>Note that the width and height are set to "wrap_content" to make the button fit neatly around the text.
</p>
<p>Below are the two buttons rendered from the XML and NinePatch image shown above.
Notice how the width and height of the button varies with the text, and the background image
stretches to accommodate it.
</p>
<img src="{@docRoot}images/ninepatch_examples.png" alt=""/>
<h2 id="tween-animation">Tween Animation</h2>
<p>A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on
the contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text.
If it has a background image, the background image will be transformed along with the text.
The {@link android.view.animation animation package} provides all the classes used in a tween animation.</p>
<p>A sequence of animation instructions defines the tween animation, defined by either XML or Android code.
Like defining a layout, an XML file is recommended because it's more readable, reusable, and swappable
than hard-coding the animation. In the example below, we use XML. (To learn more about defining an animation
in your application code, instead of XML, refer to the
{@link android.view.animation.AnimationSet} class and other {@link android.view.animation.Animation} subclasses.)</p>
<p>The animation instructions define the transformations that you want to occur, when they will occur,
and how long they should take to apply. Transformations can be sequential or simultaneous &mdash;
for example, you can have the contents of a TextView move from left to right, and then
rotate 180 degrees, or you can have the text move and rotate simultaneously. Each transformation
takes a set of parameters specific for that transformation (starting size and ending size
for size change, starting angle and ending angle for rotation, and so on), and
also a set of common parameters (for instance, start time and duration). To make
several transformations happen simultaneously, give them the same start time;
to make them sequential, calculate the start time plus the duration of the preceding transformation.
</p>
<p>The animation XML file belongs in the <code>res/anim/</code> directory of your Android project.
The file must have a single root element: this will be either a single <code>&lt;alpha&gt;</code>,
<code>&lt;scale&gt;</code>, <code>&lt;translate&gt;</code>, <code>&lt;rotate&gt;</code>, interpolator element,
or <code>&lt;set&gt;</code> element that holds groups of these elements (which may include another
<code>&lt;set&gt;</code>). By default, all animation instructions are applied simultaneously.
To make them occur sequentially, you must specify the <code>startOffset</code> attribute, as shown in the example below.
</p>
<p>The following XML from one of the ApiDemos is used to stretch,
then simultaneously spin and rotate a View object.
</p>
<pre>
&lt;set android:shareInterpolator="false"&gt;
&lt;scale
android:interpolator="&#64;android:anim/accelerate_decelerate_interpolator"
android:fromXScale="1.0"
android:toXScale="1.4"
android:fromYScale="1.0"
android:toYScale="0.6"
android:pivotX="50%"
android:pivotY="50%"
android:fillAfter="false"
android:duration="700" /&gt;
&lt;set android:interpolator="&#64;android:anim/decelerate_interpolator"&gt;
&lt;scale
android:fromXScale="1.4"
android:toXScale="0.0"
android:fromYScale="0.6"
android:toYScale="0.0"
android:pivotX="50%"
android:pivotY="50%"
android:startOffset="700"
android:duration="400"
android:fillBefore="false" /&gt;
&lt;rotate
android:fromDegrees="0"
android:toDegrees="-45"
android:toYScale="0.0"
android:pivotX="50%"
android:pivotY="50%"
android:startOffset="700"
android:duration="400" /&gt;
&lt;/set&gt;
&lt;/set&gt;
</pre>
<p>Screen coordinates (not used in this example) are (0,0) at the upper left hand corner,
and increase as you go down and to the right.</p>
<p>Some values, such as pivotX, can be specified relative to the object itself or relative to the parent.
Be sure to use the proper format for what you want ("50" for 50% relative to the parent, or "50%" for 50%
relative to itself).</p>
<p>You can determine how a transformation is applied over time by assigning an
{@link android.view.animation.Interpolator}. Android includes
several Interpolator subclasses that specify various speed curves: for instance,
{@link android.view.animation.AccelerateInterpolator} tells
a transformation to start slow and speed up. Each one has an attribute value that can be applied in the XML.</p>
<p>With this XML saved as <code>hyperspace_jump.xml</code> in the <code>res/anim/</code> directory of the
project, the following Java code will reference it and apply it to an {@link android.widget.ImageView} object
from the layout.
</p>
<pre>
ImageView spaceshipImage = (ImageView) findViewById(R.id.spaceshipImage);
Animation hyperspaceJumpAnimation = AnimationUtils.loadAnimation(this, R.anim.hyperspace_jump);
spaceshipImage.startAnimation(hyperspaceJumpAnimation);
</pre>
<p>As an alternative to <code>startAnimation()</code>, you can define a starting time for the animation with
<code>{@link android.view.animation.Animation#setStartTime(long) Animation.setStartTime()}</code>,
then assign the animation to the View with
<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>.
</p>
<p>For more information on the XML syntax, available tags and attributes, see <a
href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>
<p class="note"><strong>Note:</strong> Regardless of how your animation may move or resize, the bounds of the
View that holds your animation will not automatically adjust to accommodate it. Even so, the animation will still
be drawn beyond the bounds of its View and will not be clipped. However, clipping <em>will occur</em>
if the animation exceeds the bounds of the parent View.</p>
<h2 id="frame-animation">Frame Animation</h2>
<p>This is a traditional animation in the sense that it is created with a sequence of different
images, played in order, like a roll of film. The {@link android.graphics.drawable.AnimationDrawable}
class is the basis for frame animations.</p>
<p>While you can define the frames of an animation in your code, using the
{@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML
file that lists the frames that compose the animation. Like the tween animation above, the XML file for this kind
of animation belongs in the <code>res/drawable/</code> directory of your Android project. In this case,
the instructions are the order and duration for each frame of the animation.</p>
<p>The XML file consists of an <code>&lt;animation-list></code> element as the root node and a series
of child <code>&lt;item></code> nodes that each define a frame: a drawable resource for the frame and the frame duration.
Here's an example XML file for a frame-by-frame animation:</p>
<pre>
&lt;animation-list xmlns:android="http://schemas.android.com/apk/res/android"
android:oneshot="true">
&lt;item android:drawable="&#64;drawable/rocket_thrust1" android:duration="200" />
&lt;item android:drawable="&#64;drawable/rocket_thrust2" android:duration="200" />
&lt;item android:drawable="&#64;drawable/rocket_thrust3" android:duration="200" />
&lt;/animation-list>
</pre>
<p>This animation runs for just three frames. By setting the <code>android:oneshot</code> attribute of the
list to <var>true</var>, it will cycle just once then stop and hold on the last frame. If it is set <var>false</var> then
the animation will loop. With this XML saved as <code>rocket_thrust.xml</code> in the <code>res/drawable/</code> directory
of the project, it can be added as the background image to a View and then called to play. Here's an example Activity,
in which the animation is added to an {@link android.widget.ImageView} and then animated when the screen is touched:</p>
<pre>
AnimationDrawable rocketAnimation;
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image);
rocketImage.setBackgroundResource(R.drawable.rocket_thrust);
rocketAnimation = (AnimationDrawable) rocketImage.getBackground();
}
public boolean onTouchEvent(MotionEvent event) {
if (event.getAction() == MotionEvent.ACTION_DOWN) {
rocketAnimation.start();
return true;
}
return super.onTouchEvent(event);
}
</pre>
<p>It's important to note that the <code>start()</code> method called on the AnimationDrawable cannot be
called during the <code>onCreate()</code> method of your Activity, because the AnimationDrawable is not yet fully attached
to the window. If you want to play the animation immediately, without
requiring interaction, then you might want to call it from the
<code>{@link android.app.Activity#onWindowFocusChanged(boolean) onWindowFocusChanged()}</code> method in
your Activity, which will get called when Android brings your window into focus.</p>
<p>For more information on the XML syntax, available tags and attributes, see <a
href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p>
base/docs/html/guide/topics/graphics/index.jd
+203
View File
@@ -0,0 +1,203 @@
page.title=Graphics
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#options">Consider your Options</a></li>
<li><a href="#draw-to-view">Simple Graphics Inside a View</a></li>
<li><a href="#draw-with-canvas">Draw with a Canvas</a>
<ol>
<li><a href="#on-view">On a View</a></li>
<li><a href="#on-surfaceview">On a SurfaceView</a></li>
</ol>
</li>
</ol>
</div>
</div>
<p>Android graphics are powered by a custom 2D graphics library and OpenGL ES 1.0
for high performance 3D graphics. The most common 2D graphics APIs can be found in the
{@link android.graphics.drawable drawable package}. OpenGL APIs are available
from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES package},
plus some Android {@link android.opengl OpenGL utilities}.</p>
<p>When starting a project, it's important to consider exactly what your graphical demands will be.
Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations
for a rather static application should be implemented much differently than graphics and animations
for an interactive game or 3D rendering.</p>
<p>Here, we'll discuss a few of the options you have for drawing graphics on Android,
and which tasks they're best suited for.</p>
<p>If you're specifically looking for information on drawing 3D graphics, this page won't
help a lot. However, the information below about how to <a href="#draw-with-canvas">Draw with a
Canvas</a> (and the section on SurfaceView),
will give you a quick idea of how you should draw to the View hierarchy. For more information
on Android's 3D graphic utilities (provided by the OpenGL ES API),
read <a href="opengl.html">3D with OpenGL</a> and refer to other OpenGL documentation.</p>
<h2 id="options">Consider your Options</h2>
<p>When drawing 2D graphics, you'll typically do so in one of two ways:</p>
<ol type="a">
<li>Draw your graphics or animations into a View object from your layout. In this manner,
the drawing (and any animation) of your graphics is handled by the system's
normal View hierarchy drawing process &mdash; you simply define the graphics to go inside the View.</li>
<li>Draw your graphics directly to a Canvas. This way, you personally call the appropriate class's
<code>draw()</code> method (passing it your Canvas), or one of the Canvas <code>draw...()</code> methods (like
<code>{@link android.graphics.Canvas#drawPicture(Picture,Rect) drawPicture()}</code>). In doing so, you are also in
control of any animation.</li>
</ol>
<p>Option "a," drawing to a View, is your best choice when you want to draw simple graphics that do not
need to change dynamically and are not part of a performance-intensive game. For example, you should
draw your graphics into a View when you want to display a static graphic or predefined animation, within
an otherwise static application. Read <a href="#draw-to-view">Simple Graphics Inside a View</a>.</li>
<p>Option "b," drawing to a Canvas, is better when your application needs to regularly re-draw itself.
Basically, any video game should be drawing to the Canvas on its own. However, there's more than
one way to do this: </p>
<ul>
<li>In the same thread as your UI Activity, wherein you create a custom View component in
your layout, call <code>{@link android.view.View#invalidate()}</code> and then handle the
<code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback..</li>
<li>Or, in a separate thread, wherein you manage a {@link android.view.SurfaceView} and
perform draws to the Canvas as fast as your thread is capable
(you do not need to request <code>invalidate()</code>).</li>
</ul>
<p>...Begin by reading <a href="#draw-with-canvas">Draw with a Canvas</a>.</p>
<h2 id="draw-to-view">Simple Graphics Inside a View</h2>
<p>If you'll be drawing some simple graphics (images, shapes, colors, pre-defined animations, etc.),
then you should probably just draw to the background of a View or
to the content of an {@link android.widget.ImageView} in your layout.
In this case, you can skip the rest of this document and learn how to
draw graphics and animations in the <a href="2d-graphics.html">2D Graphics</a> document.
</p>
<h2 id="draw-with-canvas">Draw with a Canvas</h2>
<p>When you're writing an application in which you would like to perform specialized drawing
and/or control the animation of graphics,
you should do so by drawing through a {@link android.graphics.Canvas}. A Canvas works for you as
a pretense, or interface, to the actual surface upon which your graphics will be drawn &mdash; it
holds all of your "draw" calls. Via the Canvas, your drawing is actually performed upon an
underlying {@link android.graphics.Bitmap}, which is placed into the window.</p>
<p>In the event that you're drawing within the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code>
callback method, the Canvas is provided for you and you need only place your drawing calls upon it.
You can also acquire a Canvas from <code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code>,
when dealing with a SurfaceView object. (Both of these scenarios are discussed in the following sections.)
However, if you need to create a new Canvas, then you must define the {@link android.graphics.Bitmap}
upon which drawing will actually be performed. The Bitmap is always required for a Canvas. You can set up
a new Canvas like this:</p>
<pre>
Bitmap b = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888);
Canvas c = new Canvas(b);
</pre>
<p>Now your Canvas will draw onto the defined Bitmap. After drawing upon it with the Canvas, you can then carry your
Bitmap to another Canvas with one of the <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Matrix,Paint)
Canvas.drawBitmap(Bitmap,...)}</code> methods. It's recommended that you ultimately draw your final
graphics through a Canvas offered to you
by <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code> or
<code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code> (see the following sections).</p>
<p>The {@link android.graphics.Canvas} class has its own set of drawing methods that you can use,
like <code>drawBitmap(...)</code>, <code>drawRect(...)</code>, <code>drawText(...)</code>, and many more.
Other classes that you might use also have <code>draw()</code> methods. For example, you'll probably
have some {@link android.graphics.drawable.Drawable} objects that you want to put on the Canvas. Drawable
has its own <code>{@link android.graphics.drawable.Drawable#draw(Canvas) draw()}</code> method
that takes your Canvas as an argument.</p>
<h3 id="on-view">On a View</h3>
<p>If your application does not require a significant amount of processing or
frame-rate speed (perhaps for a chess game, a snake game,
or another slowly-animated application), then you should consider creating a custom View component
and drawing with a Canvas in <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code>.
The most convenient aspect of doing so is that the Android framework will
provide you with a pre-defined Canvas to which you will place your drawing calls.</p>
<p>To start, extend the {@link android.view.View} class (or descendant thereof) and define
the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback method. This method will be called by the Android
framework to request that your View draw itself. This is where you will perform all your calls
to draw through the {@link android.graphics.Canvas}, which is passed to you through the <code>onDraw()</code> callback.</p>
<p>The Android framework will only call <code>onDraw()</code> as necessary. Each time that
your application is prepared to be drawn, you must request your View be invalidated by calling
<code>{@link android.view.View#invalidate()}</code>. This indicates that you'd like your View to be drawn and
Android will then call your <code>onDraw()</code> method (though is not guaranteed that the callback will
be instantaneous). </p>
<p>Inside your View component's <code>onDraw()</code>, use the Canvas given to you for all your drawing,
using various <code>Canvas.draw...()</code> methods, or other class <code>draw()</code> methods that
take your Canvas as an argument. Once your <code>onDraw()</code> is complete, the Android framework will
use your Canvas to draw a Bitmap handled by the system.</p>
<p class="note"><strong>Note: </strong> In order to request an invalidate from a thread other than your main
Activity's thread, you must call <code>{@link android.view.View#postInvalidate()}</code>.</p>
<p>Also read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>
for a guide to extending a View class, and <a href="2d-graphics.html">2D Graphics: Drawables</a> for
information on using Drawable objects like images from your resources and other primitive shapes.</p>
<p>For a sample application, see the Snake game, in the SDK samples folder:
<code>&lt;your-sdk-directory>/samples/Snake/</code>.</p>
<h3 id="on-surfaceview">On a SurfaceView</h3>
<p>The {@link android.view.SurfaceView} is a special subclass of View that offers a dedicated
drawing surface within the View hierarchy. The aim is to offer this drawing surface to
an application's secondary thread, so that the application isn't required
to wait until the system's View hierarchy is ready to draw. Instead, a secondary thread
that has reference to a SurfaceView can draw to its own Canvas at its own pace.</p>
<p>To begin, you need to create a new class that extends {@link android.view.SurfaceView}. The class should also
implement {@link android.view.SurfaceHolder.Callback}. This subclass is an interface that will notify you
with information about the underlying {@link android.view.Surface}, such as when it is created, changed, or destroyed.
These events are important so that you know when you can start drawing, whether you need
to make adjustments based on new surface properties, and when to stop drawing and potentially
kill some tasks. Inside your SurfaceView class is also a good place to define your secondary Thread class, which will
perform all the drawing procedures to your Canvas.</p>
<p>Instead of handling the Surface object directly, you should handle it via
a {@link android.view.SurfaceHolder}. So, when your SurfaceView is initialized, get the SurfaceHolder by calling
<code>{@link android.view.SurfaceView#getHolder()}</code>. You should then notify the SurfaceHolder that you'd
like to receive SurfaceHolder callbacks (from {@link android.view.SurfaceHolder.Callback}) by calling
{@link android.view.SurfaceHolder#addCallback(SurfaceHolder.Callback) addCallback()}
(pass it <var>this</var>). Then override each of the
{@link android.view.SurfaceHolder.Callback} methods inside your SurfaceView class.</p>
<p>In order to draw to the Surface Canvas from within your second thread, you must pass the thread your SurfaceHandler
and retrieve the Canvas with <code>{@link android.view.SurfaceHolder#lockCanvas() lockCanvas()}</code>.
You can now take the Canvas given to you by the SurfaceHolder and do your necessary drawing upon it.
Once you're done drawing with the Canvas, call
<code>{@link android.view.SurfaceHolder#unlockCanvasAndPost(Canvas) unlockCanvasAndPost()}</code>, passing it
your Canvas object. The Surface will now draw the Canvas as you left it. Perform this sequence of locking and
unlocking the canvas each time you want to redraw.</p>
<p class="note"><strong>Note:</strong> On each pass you retrieve the Canvas from the SurfaceHolder,
the previous state of the Canvas will be retained. In order to properly animate your graphics, you must re-paint the
entire surface. For example, you can clear the previous state of the Canvas by filling in a color
with <code>{@link android.graphics.Canvas#drawColor(int) drawColor()}</code> or setting a background image
with <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Rect,RectF,Paint) drawBitmap()}</code>. Otherwise,
you will see traces of the drawings you previously performed.</p>
<p>For a sample application, see the Lunar Lander game, in the SDK samples folder:
<code>&lt;your-sdk-directory>/samples/LunarLander/</code>. Or,
browse the source in the <a href="{@docRoot}guide/samples/index.html">Sample Code</a> section.</p>
base/docs/html/guide/topics/graphics/opengl.jd
+53
View File
@@ -0,0 +1,53 @@
page.title=3D with OpenGL
parent.title=2D and 3D Graphics
parent.link=index.html
@jd:body
<p>Android includes support for high performance 3D graphics
via the OpenGL API &mdash; specifically, the OpenGL ES API.</p>
<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded
devices. Versions of <a href="http://www.khronos.org/opengles/">OpenGL ES</a> are loosely peered to versions of the primary
OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds
to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL
1.3 on a desktop system, it should be possible on Android.</p>
<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL
ES API. However, it may not be identical, so watch out for deviations.</p>
<h2>Using the API</h2>
<p>Here's how to use the API at an extremely high level:</p>
<ol>
<li>Write a custom View subclass.</li>
<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li>
<li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li>
</ol>
<p>For an example of this usage model (based on the classic GL ColorCube), showing how to use
it with threads can be found in
<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>.
</p>
<p>Writing a summary of how to actually write 3D applications using OpenGL is
beyond the scope of this text and is left as an exercise for the reader.</p>
<h2>Links to Additional Information</h2>
<p>Information about OpenGL ES can be
found at <a title="http://www.khronos.org/opengles/"
href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p>
<p>Information specifically
about OpenGL ES 1.0 (including a detailed specification) can be found
at <a title="http://www.khronos.org/opengles/1_X/"
href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p>
<p>The documentation for the Android {@link javax.microedition.khronos.opengles
OpenGL ES implementations} are also available.</p>
<p>Finally, note that though Android does include some basic support for
OpenGL ES 1.1, the support is <strong>not complete</strong>, and should not be relied
upon at this time.</p>