diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/html/about/versions/android-4.0.jd | 54 | ||||
| -rw-r--r-- | docs/html/google/gcm/gcm.jd | 1 | ||||
| -rw-r--r-- | docs/html/guide/components/services.jd | 26 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 4 | ||||
| -rw-r--r-- | docs/html/guide/topics/graphics/hardware-accel.jd | 518 | ||||
| -rw-r--r-- | docs/html/guide/topics/graphics/renderscript/graphics.jd | 994 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/activity-element.jd | 34 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/application-element.jd | 89 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/advanced.jd | 158 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/compute.jd | 528 | ||||
| -rw-r--r-- | docs/html/guide/topics/renderscript/index.jd | 20 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/drawable-resource.jd | 7 | ||||
| -rw-r--r-- | docs/html/images/mediadrm_decryption_sequence.png | bin | 0 -> 67604 bytes | |||
| -rw-r--r-- | docs/html/images/mediadrm_overview.png | bin | 0 -> 35383 bytes | |||
| -rw-r--r-- | docs/html/training/location/receive-location-updates.jd | 25 |
15 files changed, 793 insertions, 1665 deletions
diff --git a/docs/html/about/versions/android-4.0.jd b/docs/html/about/versions/android-4.0.jd index c1a9180..1d81bc2 100644 --- a/docs/html/about/versions/android-4.0.jd +++ b/docs/html/about/versions/android-4.0.jd @@ -123,7 +123,7 @@ to invoke an action that indicates the user wants to add a contact to a social n receiving the app uses it to invite the specified contact to that social network. Most apps will be on the receiving-end of this operation. For example, the built-in People app invokes the invite intent when the user selects "Add connection" for a specific -social app that's listed in a person's contact details.</p> +social app that's listed in a person's contact details.</p> <p>To make your app visible as in the "Add connection" list, your app must provide a sync adapter to sync contact information from your social network. You must then indicate to the system that your @@ -328,7 +328,7 @@ image (usually done by calling the {@link android.opengl.GLES20#glTexImage2D glT function). You may provide multiple mipmap levels. If the output texture has not been bound to a texture image, it will be automatically bound by the effect as a {@link android.opengl.GLES20#GL_TEXTURE_2D} and with one mipmap level (0), which will have the same -size as the input.</p> +size as the input.</p> <p>All effects listed in {@link android.media.effect.EffectFactory} are guaranteed to be supported. However, some additional effects available from external libraries are not supported by all devices, @@ -453,7 +453,7 @@ android.hardware.Camera.Parameters#getMaxNumDetectedFaces()} and ensure the retu value is greater than zero. Also, some devices may not support identification of eyes and mouth, in which case, those fields in the {@link android.hardware.Camera.Face} object will be null.</p> - + <h4>Focus and metering areas</h4> <p>Camera apps can now control the areas that the camera uses for focus and for metering white @@ -496,7 +496,7 @@ added in API level 9.</p> <h4>Other camera features</h4> -<ul> +<ul> <li>While recording video, you can now call {@link android.hardware.Camera#takePicture takePicture()} to save a photo without interrupting the video session. Before doing so, you should call {@link android.hardware.Camera.Parameters#isVideoSnapshotSupported} to be sure the hardware @@ -776,7 +776,7 @@ methods that allow the view and its parents to add more contextual information t <li>When invoked, the {@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()} and {@link android.view.View#sendAccessibilityEventUnchecked sendAccessibilityEventUnchecked()} methods defer -to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}. +to {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}. <p>Custom implementations of {@link android.view.View} might want to implement {@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} to attach additional accessibility information to the {@link @@ -1023,46 +1023,6 @@ roaming or connected to Wi-Fi.</p> -<h3 id="RenderScript">RenderScript</h3> - -<p>Three major features have been added to RenderScript:</p> - -<ul> - <li>Off-screen rendering to a framebuffer object</li> - <li>Rendering inside a view</li> - <li>RS for each from the framework APIs</li> -</ul> - -<p>The {@link android.renderscript.Allocation} class now supports a {@link -android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} memory space, which allows you to -render things directly into the {@link android.renderscript.Allocation} and use it as a framebuffer -object.</p> - -<p>{@link android.renderscript.RSTextureView} provides a means to display RenderScript graphics -inside of a {@link android.view.View}, unlike {@link android.renderscript.RSSurfaceView}, which -creates a separate window. This key difference allows you to do things such as move, transform, or -animate an {@link android.renderscript.RSTextureView} as well as draw RenderScript graphics inside -a view that lies within an activity layout.</p> - -<p>The {@link android.renderscript.Script#forEach Script.forEach()} method allows you to call -RenderScript compute scripts from the VM level and have them automatically delegated to available -cores on the device. You do not use this method directly, but any compute RenderScript that you -write will have a {@link android.renderscript.Script#forEach forEach()} method that you can call in -the reflected RenderScript class. You can call the reflected {@link -android.renderscript.Script#forEach forEach()} method by passing in an input {@link -android.renderscript.Allocation} to process, an output {@link android.renderscript.Allocation} to -write the result to, and a {@link android.renderscript.FieldPacker} data structure in case the -RenderScript needs more information. Only one of the {@link android.renderscript.Allocation}s is -necessary and the data structure is optional.</p> - - - - - - - - - <h3 id="Enterprise">Enterprise</h3> <p>Android 4.0 expands the capabilities for enterprise application with the following features.</p> @@ -1759,7 +1719,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe notes for more information.</li> </ul> </dd> - + <dt><a href="android-3.1.html">Android 3.1</a></dt> <dd> <ul> @@ -1782,7 +1742,7 @@ android.net.rtp} documentation.</li> notes for many more new APIs.</li> </ul> </dd> - + <dt><a href="android-3.2.html">Android 3.2</a></dt> <dd> <ul> diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index 4d26e6b..ceb82b0 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -645,6 +645,7 @@ Check that the token you're sending inside the <code>Authorization</code> header # curl --header "Authorization: key=$api_key" --header Content-Type:"application/json" https://android.googleapis.com/gcm/send -d "{\"registration_ids\":[\"ABC\"]}"</pre> + If you receive a 401 HTTP status code, your API key is not valid. Otherwise you should see something like this:<br/> <pre> diff --git a/docs/html/guide/components/services.jd b/docs/html/guide/components/services.jd index 6e5dfd2..30da33a 100644 --- a/docs/html/guide/components/services.jd +++ b/docs/html/guide/components/services.jd @@ -252,19 +252,6 @@ document.</p> <h2 id="CreatingStartedService">Creating a Started Service</h2> -<div class="sidebox-wrapper"> -<div class="sidebox"> - <h2>Targeting Android 1.6 or lower</h2> - <p>If you're building an application for Android 1.6 or lower, you need -to implement {@link android.app.Service#onStart onStart()}, instead of {@link -android.app.Service#onStartCommand onStartCommand()} (in Android 2.0, -{@link android.app.Service#onStart onStart()} was deprecated in favor of {@link -android.app.Service#onStartCommand onStartCommand()}).</p> - <p>For more information about providing compatibility with versions of Android older than 2.0, see -the {@link android.app.Service#onStartCommand onStartCommand()} documentation.</p> -</div> -</div> - <p>A started service is one that another component starts by calling {@link android.content.Context#startService startService()}, resulting in a call to the service's {@link android.app.Service#onStartCommand onStartCommand()} method.</p> @@ -687,9 +674,12 @@ Intent notificationIntent = new Intent(this, ExampleActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); notification.setLatestEventInfo(this, getText(R.string.notification_title), getText(R.string.notification_message), pendingIntent); -startForeground(ONGOING_NOTIFICATION, notification); +startForeground(ONGOING_NOTIFICATION_ID, notification); </pre> +<p class="caution"><strong>Caution:</strong> The integer ID you give to {@link +android.app.Service#startForeground startForeground()} must not be 0.</p> + <p>To remove the service from the foreground, call {@link android.app.Service#stopForeground stopForeground()}. This method takes a boolean, indicating @@ -697,14 +687,6 @@ whether to remove the status bar notification as well. This method does <em>not< service. However, if you stop the service while it's still running in the foreground, then the notification is also removed.</p> -<p class="note"><strong>Note:</strong> The methods {@link -android.app.Service#startForeground startForeground()} and {@link -android.app.Service#stopForeground stopForeground()} were introduced in Android 2.0 (API Level -5). In order to run your service in the foreground on older versions of the platform, you must -use the previous {@code setForeground()} method—see the {@link -android.app.Service#startForeground startForeground()} documentation for information about how -to provide backward compatibility.</p> - <p>For more information about notifications, see <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Creating Status Bar Notifications</a>.</p> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 5f9f530..16dca9d 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -326,11 +326,11 @@ </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/renderscript/compute.html"> - <span class="en">Renderscript</span></a> + <span class="en">RenderScript</span></a> </li> <li><a href="<?cs var:toroot ?>guide/topics/renderscript/advanced.html"> - <span class="en">Advanced Renderscript</span></a> + <span class="en">Advanced RenderScript</span></a> </li> <li><a href="<?cs var:toroot ?>guide/topics/renderscript/reference.html"> <span class="en">Runtime API Reference</span></a> diff --git a/docs/html/guide/topics/graphics/hardware-accel.jd b/docs/html/guide/topics/graphics/hardware-accel.jd index 04fb564..8ba6676 100644 --- a/docs/html/guide/topics/graphics/hardware-accel.jd +++ b/docs/html/guide/topics/graphics/hardware-accel.jd @@ -47,35 +47,24 @@ parent.link=index.html </div> </div> - <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline is designed to - better support hardware acceleration. Hardware acceleration carries out all drawing operations - that are performed on a {@link android.view.View}'s canvas using the GPU. Because of the - increased resources required to enable hardware acceleration, your app will consume more RAM.</p> - - <p>The easiest way to enable hardware acceleration is to turn it on - globally for your entire application. If your application uses only standard views and {@link - android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse - drawing effects. However, because hardware acceleration is not supported for all of the 2D drawing - operations, turning it on might affect some of your applications that use custom views or drawing - calls. Problems usually manifest themselves as invisible elements, exceptions, or wrongly - rendered pixels. To remedy this, Android gives you the option to enable or disable hardware - acceleration at the following levels:</p> - - <ul> - <li>Application</li> - - <li>Activity</li> - - <li>Window</li> - - <li>View</li> - </ul> - - <p>If your application performs custom drawing, test your application on actual hardware -devices with hardware acceleration turned on to find any problems. The <a -href="#drawing-support">Unsupported drawing operations</a> section describes known issues with -drawing operations that cannot be hardware accelerated and how to work around them.</p> - + <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline supports hardware + acceleration, meaning that all drawing operations that are performed on a {@link + android.view.View}'s canvas use the GPU. Because of the increased resources required to enable + hardware acceleration, your app will consume more RAM.</p> + + <p>Hardware acceleration is enabled by default if your Target API level is >=14, but can also + be explicitly enabled. If your application uses only standard views and {@link + android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse drawing + effects. However, because hardware acceleration is not supported for all of the 2D drawing + operations, turning it on might affect some of your custom views or drawing calls. Problems + usually manifest themselves as invisible elements, exceptions, or wrongly rendered pixels. To + remedy this, Android gives you the option to enable or disable hardware acceleration at multiple + levels. See <a href="#controlling">Controlling Hardware Acceleration</a>.</p> + + <p>If your application performs custom drawing, test your application on actual hardware devices + with hardware acceleration turned on to find any problems. The <a + href="#drawing-support">Unsupported drawing operations</a> section describes known issues with + hardware acceleration and how to work around them.</p> <h2 id="controlling">Controlling Hardware Acceleration</h2> <p>You can control hardware acceleration at the following levels:</p> @@ -100,12 +89,12 @@ drawing operations that cannot be hardware accelerated and how to work around th </pre> <h4>Activity level</h4> - <p>If your application does not behave properly with hardware acceleration turned on globally, - you can control it for individual activities as well. To enable or disable hardware acceleration - at the activity level, you can use the <code>android:hardwareAccelerated</code> - attribute for the <a href="{@docRoot}guide/topics/manifest/activity-element.html"> - <code><activity></code></a> element. The following example enables hardware acceleration -for the entire application but disables it for one activity:</p> + <p>If your application does not behave properly with hardware acceleration turned on globally, you + can control it for individual activities as well. To enable or disable hardware acceleration at + the activity level, you can use the <code>android:hardwareAccelerated</code> attribute for + the <a href="{@docRoot}guide/topics/manifest/activity-element.html"> + <code><activity></code></a> element. The following example enables hardware acceleration for + the entire application but disables it for one activity:</p> <pre> <application android:hardwareAccelerated="true"> @@ -228,8 +217,7 @@ changed.</li> <p>With this model, you cannot rely on a view intersecting the dirty region to have its {@link android.view.View#draw draw()} method executed. To ensure that the Android system records a view’s display list, you must call {@link android.view.View#invalidate invalidate()}. Forgetting - to do so causes a view to look the same even after changing it, which is an easier bug to find if - it happens.</p> + to do so causes a view to look the same even after it has been changed.</p> <p>Using display lists also benefits animation performance because setting specific properties, such as alpha or rotation, does not require invalidating the targeted view (it is done @@ -270,119 +258,353 @@ changed.</li> android.graphics.Canvas} drawing operations as well as many less-used operations. All of the drawing operations that are used to render applications that ship with Android, default widgets and layouts, and common advanced visual effects such as reflections and tiled textures are - supported. The following list describes known operations that are <strong>not supported</strong> - with hardware acceleration:</p> - - <ul> - <li> - <strong>Canvas</strong> - - <ul> - <li>{@link android.graphics.Canvas#clipPath clipPath()}</li> - - <li>{@link android.graphics.Canvas#clipRegion clipRegion()}</li> - - <li>{@link android.graphics.Canvas#drawPicture drawPicture()}</li> - - <li>{@link android.graphics.Canvas#drawTextOnPath drawTextOnPath()}</li> - - <li>{@link android.graphics.Canvas#drawVertices drawVertices()}</li> - </ul> - </li> - - <li> - <strong>Paint</strong> - - <ul> - <li>{@link android.graphics.Paint#setLinearText setLinearText()}</li> - - <li>{@link android.graphics.Paint#setMaskFilter setMaskFilter()}</li> - - <li>{@link android.graphics.Paint#setRasterizer setRasterizer()}</li> - </ul> - </li> - - <li> - <strong>Xfermodes</strong> - - <ul> - <li>{@link android.graphics.AvoidXfermode AvoidXfermode}</li> - - <li>{@link android.graphics.PixelXorXfermode PixelXorXfermode}</li> - </ul> - </li> - </ul> - - <p>In addition, some operations behave differently with hardware acceleration enabled:</p> - - <ul> - <li> - <strong>Canvas</strong> - - <ul> - <li>{@link android.graphics.Canvas#clipRect clipRect()}: <code>XOR</code>, - <code>Difference</code> and <code>ReverseDifference</code> clip modes are ignored. 3D - transforms do not apply to the clip rectangle</li> - - <li>{@link android.graphics.Canvas#drawBitmapMesh drawBitmapMesh()}: colors array is - ignored</li> - </ul> - </li> - - <li> - <strong>Paint</strong> - - <ul> - <li>{@link android.graphics.Paint#setDither setDither()}: ignored</li> - - <li>{@link android.graphics.Paint#setFilterBitmap setFilterBitmap()}: filtering is always - on</li> - - <li>{@link android.graphics.Paint#setShadowLayer setShadowLayer()}: works with text - only</li> - </ul> - </li> - - <li> - <strong>PorterDuffXfermode</strong> - - <ul> - <li>{@link android.graphics.PorterDuff.Mode#DARKEN PorterDuff.Mode.DARKEN} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - - <li>{@link android.graphics.PorterDuff.Mode#LIGHTEN PorterDuff.Mode.LIGHTEN} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - - <li>{@link android.graphics.PorterDuff.Mode#OVERLAY PorterDuff.Mode.OVERLAY} will - be equivalent to {@link android.graphics.PorterDuff.Mode#SRC_OVER} when blending - against the framebuffer.</li> - </ul> - </li> - - <li> - <strong>ComposeShader</strong> - - <ul> - <li>{@link android.graphics.ComposeShader} can only contain shaders of different types (a - {@link android.graphics.BitmapShader} and a {@link android.graphics.LinearGradient} for - instance, but not two instances of {@link android.graphics.BitmapShader} )</li> - - <li>{@link android.graphics.ComposeShader} cannot contain a {@link - android.graphics.ComposeShader}</li> - </ul> - </li> - </ul> + supported.</p> + + <p>The following table describes the support level of various operations across API levels:</p> + + <style type="text/css"> + .tblGenFixed, .tblGeneric{font-size:15px}.tblGenFixed td {padding:0 3px;letter-spacing:0;word-spacing:0;background-color:#fff;z-index:1;border-top:0px none;border-left:0px none;border-bottom:1px solid #CCC;border-right:1px solid #CCC;} .dn {display:none} .tblGenFixed td.s0 {background-color:white;border-top:1px solid #CCC;border-left:1px solid #CCC;} .tblGenFixed td.s1 {background-color:#434343;color:#ffffff;text-align:center;border-top:1px solid #CCC;} .tblGenFixed td.s2 {background-color:#d9d9d9;color:#000000;text-align:center;} .tblGenFixed td.s3 {background-color:white;color:#000000;text-align:center;} .tblGenFixed td.s5 {background-color:#434343;color:#ffffff;text-align:left;border-left:1px solid #CCC;} .tblGenFixed td.s10 {background-color:white;font-family:courier new,monospace;color:#000000;text-align:right;border-left:1px solid #CCC;} .tblGenFixed td.g_pos {background-color:#d9d9d9;color:#6aa84f;text-align:center;} .tblGenFixed td.g_neg {background-color:#d9d9d9;color:#980000;text-align:center;} .tblGenFixed td.w_pos {background-color:white;color:#6aa84f;text-align:center;} .tblGenFixed td.w_neg {background-color:white;color:#980000;text-align:center;} + </style> + <table border="0" cellpadding="0" cellspacing="0" class="tblGenFixed" id="tblMain"> + <tbody> + <tr class="rShim"> + <td class="rShim" style="width:380px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + </tr> + <tr> + <td rowspan="2" class="s0"></td> + <td colspan="4" class="s1">API level</td> + </tr> + <tr> + <td style="display:none;"></td> + <td class="s2">< 16</td> + <td class="s3">16</td> + <td class="s2">17</td> + <td class="s3">18</td> + </tr> + <tr> + <td colspan="5" class="s5">Canvas</td> + </tr> + <tr> + <td class="s10">drawBitmapMesh() (colors array)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawPicture()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">drawPosText()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawTextOnPath()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">drawVertices()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setDrawFilter()</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRegion()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.XOR)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.Difference)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect(Region.Op.ReverseDifference)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">clipRect() with rotation/perspective</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td colspan="5" class="s5">Paint</td> + </tr> + <tr> + <td class="s10">setAntiAlias() (for text)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setAntiAlias() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setFilterBitmap()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_pos">✓</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setLinearText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setMaskFilter()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setPathEffect() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setRasterizer()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setShadowLayer() (other than text)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setStrokeCap() (for lines)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + <tr> + <td class="s10">setStrokeCap() (for points)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">setSubpixelText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td colspan="5" class="s5">Xfermode</td> + </tr> + <tr> + <td class="s10">AvoidXfermode</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PixelXorXfermode</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.DARKEN (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.LIGHTEN (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">PorterDuff.Mode.OVERLAY (framebuffer)</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td colspan="5" class="s5">Shader</td> + </tr> + <tr> + <td class="s10">ComposeShader inside ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">Same type shaders inside ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + </tr> + <tr> + <td class="s10">Local matrix on ComposeShader</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + </tr> + </tbody> + </table> + + <h3 id="scaling">Canvas Scaling</h3> + + <p>The hardware accelerated 2D rendering pipeline was built first to support unscaled drawing, + with some drawing operations degrading quality significantly at higher scale values. These + operations are implemented as textures drawn at scale 1.0, transformed by the GPU. In API level + <17, using these operations will result in scaling artifacts increasing with scale.</p> + + The following table shows when implementation was changed to correctly handle large scales: + + <table border="0" cellpadding="0" cellspacing="0" class="tblGenFixed" id="tblMain"> + <tbody> + <tr class="rShim"> + <td class="rShim" style="width:380px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + <td class="rShim" style="width:120px;"></td> + </tr> + <tr> + <td rowspan="2" class="s0"></td> + <td colspan="4" class="s1">API level</td> + </tr> + <tr> + <td style="display:none;"></td> + <td class="s2">< 17</td> + <td class="s3">17</td> + <td class="s2">18</td> + </tr> + <tr> + <td colspan="5" class="s5">Support for large scale factors</td> + </tr> + <tr> + <td class="s10">drawText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_pos">✓</td> + </tr> + <tr> + <td class="s10">drawPosText()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">drawTextOnPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">Simple Shapes*</td> + <td class="g_neg">✗</td> + <td class="w_pos">✓</td> + <td class="g_pos">✓</td> + </tr> + <tr> + <td class="s10">Complex Shapes*</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">drawPath()</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + <tr> + <td class="s10">Shadow layer</td> + <td class="g_neg">✗</td> + <td class="w_neg">✗</td> + <td class="g_neg">✗</td> + </tr> + </tbody> + </table> + + <p class="note"><strong>Note</strong>: 'Simple' shapes are <code>drawRect()</code>, + <code>drawCircle()</code>, <code>drawOval()</code>, <code>drawRoundRect()</code>, and + <code>drawArc()</code> (with useCenter=false) commands issued with a Paint that doesn't have a + PathEffect, and doesn't contain non-default joins (via <code>setStrokeJoin()</code> / + <code>setStrokeMiter()</code>). Other instances of those draw commands fall under 'Complex,' in + the above chart.</p> <p>If your application is affected by any of these missing features or limitations, you can turn - off hardware acceleration for just the affected portion of your application by calling - {@link android.view.View#setLayerType setLayerType(View.LAYER_TYPE_SOFTWARE, null)}. This way, -you can still take advantage of hardware acceleratin everywhere else. See <a -href="#controlling">Controlling Hardware Acceleration</a> for more information on how to enable and -disable hardware acceleration at different levels in your application. - - + off hardware acceleration for just the affected portion of your application by calling {@link + android.view.View#setLayerType setLayerType(View.LAYER_TYPE_SOFTWARE, null)}. This way, you can + still take advantage of hardware acceleration everywhere else. See <a + href="#controlling">Controlling Hardware Acceleration</a> for more information on how to enable + and disable hardware acceleration at different levels in your application. <h2 id="layers">View Layers</h2> diff --git a/docs/html/guide/topics/graphics/renderscript/graphics.jd b/docs/html/guide/topics/graphics/renderscript/graphics.jd deleted file mode 100644 index 58676ea..0000000 --- a/docs/html/guide/topics/graphics/renderscript/graphics.jd +++ /dev/null @@ -1,994 +0,0 @@ -page.title=Graphics -parent.title=Renderscript -parent.link=index.html - -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - - <ol> - <li> - <a href="#creating-graphics-rs">Creating a Graphics Renderscript</a> - <ol> - <li><a href="#creating-native">Creating the Renderscript file</a></li> - <li><a href="#creating-entry">Creating the Renderscript entry point class</a></li> - <li><a href="#creating-view">Creating the view class</a></li> - <li><a href="#creating-activity">Creating the activity class</a></li> - </ol> - </li> - <li> - <a href="#drawing">Drawing</a> - <ol> - <li><a href="#drawing-rsg">Simple drawing</a></li> - <li><a href="#drawing-mesh">Drawing with a mesh</a></li> - </ol> - </li> - <li> - <a href="#shaders">Shaders</a> - <ol> - <li><a href="#shader-bindings">Shader bindings</a></li> - <li><a href="#shader-sampler">Defining a sampler</a></li> - </ol> - </li> - <li> - <a href="#fbo">Rendering to a Framebuffer Object</a> - </li> - </ol> - - <h2>Related Samples</h2> - - <ol> - <li><a href="{@docRoot}resources/samples/RenderScript/Balls/index.html">Balls</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/FountainFbo/index.html">FountainFbo</a></li> - - <li><a href="{@docRoot}resources/samples/RenderScript/HelloWorld/index.html">Hello -World</a></li> - - <li><a -href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samples</a></li> - </ol> - </div> - </div> - - <p>Renderscript provides a number of graphics APIs for rendering, both at the Android - framework level as well as at the Renderscript runtime level. For instance, the Android framework APIs let you - create meshes and define shaders to customize the graphical rendering pipeline. The native - Renderscript graphics APIs let you draw the actual meshes to render your scene. You need to - be familiar with both APIs to appropriately render graphics on an Android-powered device.</p> - - <h2 id="creating-graphics-rs">Creating a Graphics Renderscript</h2> - - <p>Renderscript applications require various layers of code, so it is useful to create the following - files to help keep your application organized:</p> - - <dl> - <dt>The Renderscript <code>.rs</code> file</dt> - - <dd>This file contains the logic to do the graphics rendering.</dd> - - <dt>The Renderscript entry point <code>.java</code> class</dt> - - <dd>This class allows the view class to interact with the code defined in the <code>.rs</code> - file. This class contains a Renderscript object (instance of - <code>ScriptC_<em>renderscript_file</em></code>), which allows your Android framework code to - call the Renderscript code. In general, this class does much of the setup for Renderscript - such as shader and mesh building and memory allocation and binding. The SDK samples follow the - convention of naming this file ActivityRS.java, - where Activity is the name of your main activity class.</dd> - - <dt>The view <code>.java</code> class</dt> - - <dd>This class extends {@link android.renderscript.RSSurfaceView} or {@link - android.renderscript.RSTextureView} to provide a surface to render on. A {@link - android.renderscript.RSSurfaceView} consumes a whole window, but a {@link - android.renderscript.RSTextureView} allows you to draw Renderscript graphics inside of a - view and add it to a {@link android.view.ViewGroup} alongside - other views. In this class, you create a {@link android.renderscript.RenderScriptGL} context object - with a call to {@link android.renderscript.RSSurfaceView#createRenderScriptGL - RSSurfaceView.createRenderscriptGL()} or {@link android.renderscript.RSTextureView#createRenderScriptGL - RSTextureView.createRenderscriptGL()}. The {@link android.renderscript.RenderScriptGL} context object - contains information about the current rendering state of Renderscript such as the vertex and - fragment shaders. You pass this context object to the Renderscript entry point class, so that - class can modify the rendering context if needed and bind the Renderscript code to the context. Once bound, - the view class can use the Renderscript code to display graphics. - The view class should also implement callbacks for events inherited from {@link - android.view.View}, such as {@link android.view.View#onTouchEvent onTouchEvent()} and {@link - android.view.View#onKeyDown onKeyDown()} if you want to detect these types of user interactions. - The SDK samples follow the convention of naming this file ActivityView.java, - where Activity is the name of your main activity class</dd> - - <dt>The activity <code>.java</code> class</dt> - - <dd>This class is the main activity class and sets your {@link android.renderscript.RSSurfaceView} as the main content - view for this activity or uses the {@link android.renderscript.RSTextureView} alongside other views.</dd> - </dl> - <p>Figure 1 describes how these classes interact with one another in a graphics Renderscript:</p> - - <img src="{@docRoot}images/rs_graphics.png"> - <p class="img-caption"><strong>Figure 1.</strong> Graphics Renderscript overview</p> - - - <p>The following sections describe how to create an application that uses a graphics Renderscript by using - the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Renderscript Fountain - sample</a> that is provided in the SDK as a guide (some code has been modified from its original - form for simplicity).</p> - - <h3 id="creating-native">Creating the Renderscript file</h3> - - <p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> (headers) files in the - <code><project_root>/src/</code> directory. This code contains the logic to render your - graphics and declares all other necessary items such as variables, structs, - and pointers. Every graphics <code>.rs</code> file generally contains the following items:</p> - - <ul> - <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) that declares - the package name of the <code>.java</code> reflection of this Renderscript.</li> - - <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of Renderscript that - you are using (1 is the only value for now).</li> - - <li>A <code>#include "rs_graphics.rsh"</code> declaration.</li> - - <li>A <code>root()</code> function. This is the main worker function for your Renderscript and - calls Renderscript graphics functions to render scenes. This function is called every time a - frame refresh occurs, which is specified as its return value. A <code>0</code> (zero) specified for - the return value says to only render the frame when a property of the scene that you are - rendering changes. A non-zero positive integer specifies the refresh rate of the frame in - milliseconds. - - <p class="note"><strong>Note:</strong> The Renderscript runtime makes its best effort to - refresh the frame at the specified rate. For example, if you are creating a live wallpaper - and set the return value to 20, the Renderscript runtime renders the wallpaper at 50fps if it has just - enough or more resources to do so. It renders as fast as it can if not enough resources - are available.</p> - - <p>For more information on using the Renderscript graphics functions, see the <a href= - "#drawing">Drawing</a> section.</p> - </li> - - <li>An <code>init()</code> function. This allows you to do initialization of your - Renderscript before the <code>root()</code> function runs, such as assigning values to variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript. Creating this function is optional.</li> - - <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in <code>.rsh</code> files if desired)</li> - </ul> - - <p>The following code shows how the <code>fountain.rs</code> file is implemented:</p> - <pre> -#pragma version(1) - -// Tell which java package name the reflected files should belong to -#pragma rs java_package_name(com.example.android.rs.fountain) - -//declare shader binding -#pragma stateFragment(parent) - -// header with graphics APIs, must include explicitly -#include "rs_graphics.rsh" - -static int newPart = 0; - -// the mesh to render -rs_mesh partMesh; - -// the point representing where a particle is rendered -typedef struct __attribute__((packed, aligned(4))) Point { - float2 delta; - float2 position; - uchar4 color; -} Point_t; -Point_t *point; - -// main worker function that renders particles onto the screen -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - - rsgDrawMesh(partMesh); - return 1; -} - -// adds particles to the screen to render -static float4 partColor[10]; -void addParticles(int rate, float x, float y, int index, bool newColor) -{ - if (newColor) { - partColor[index].x = rsRand(0.5f, 1.0f); - partColor[index].y = rsRand(1.0f); - partColor[index].z = rsRand(1.0f); - } - float rMax = ((float)rate) * 0.02f; - int size = rsAllocationGetDimX(rsGetAllocation(point)); - uchar4 c = rsPackColorTo8888(partColor[index]); - - Point_t * np = &point[newPart]; - float2 p = {x, y}; - while (rate--) { - float angle = rsRand(3.14f * 2.f); - float len = rsRand(rMax); - np->delta.x = len * sin(angle); - np->delta.y = len * cos(angle); - np->position = p; - np->color = c; - newPart++; - np++; - if (newPart >= size) { - newPart = 0; - np = &point[newPart]; - } - } -} -</pre> - - <h3 id="creating-entry">Creating the Renderscript entry point class</h3> - - <p>When you create a Renderscript (<code>.rs</code>) file, it is helpful to create a - corresponding Android framework class that is an entry point into the <code>.rs</code> file. - The most important thing this class does is receive a {@link android.renderscript.RenderScriptGL} rendering context - object from the <a href="#creating-view">view class</a> and binds the actual Renderscript - code to the rendering context. This notifies your view class of the code that it needs - to render graphics. - </p> - - <p>In addition, this class should contain all of the things needed to set up Renderscript. - Some important things that you need to do in this class are:</p> - - <ul> - <li>Create a Renderscript object - <code>ScriptC_<em>rs_filename</em></code>. The Renderscript object is attached to the Renderscript bytecode, which is platform-independent and - gets compiled on the device when the Renderscript application runs. The bytecode is referenced - as a raw resource and is passed into the constructor for the Renderscript object. - For example, this is how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample creates the Renderscript object: - <pre> - RenderScriptGL rs; //obtained from the view class - Resources res; //obtained from the view class - ... - ScriptC_fountain mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - </pre> - </li> - <li>Allocate any necessary memory and bind it to your Renderscript code via the Renderscript object.</li> - <li>Build any necessary meshes and bind them to the Renderscript code via the Renderscript object.</li> - <li>Create any necessary programs and bind them to the Renderscript code via the Renderscript object.</li> - </ul> - - <p>The following code shows how the <a href= - "{@docRoot}resources/samples/RenderScript/Fountain/src/com/example/android/rs/fountain/FountainRS.html"> - FountainRS</a> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.content.res.Resources; -import android.renderscript.*; -import android.util.Log; - -public class FountainRS { - public static final int PART_COUNT = 50000; - - public FountainRS() { - } - - /** - * This provides us with the Renderscript context and resources - * that allow us to create the Renderscript object - */ - private Resources mRes; - private RenderScriptGL mRS; - - // Renderscript object - private ScriptC_fountain mScript; - - // Called by the view class to initialize the Renderscript context and renderer - public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - /** - * Create a shader and bind to the Renderscript context - */ - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - rs.bindProgramFragment(pfb.create()); - - /** - * Allocate memory for the particles to render and create the mesh to draw - */ - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - /** - * Create and bind the Renderscript object to the Renderscript context - */ - mScript = new ScriptC_fountain(mRS, mRes, R.raw.fountain); - mScript.set_partMesh(sm); - mScript.bind_point(points); - mRS.bindRootScript(mScript); - } - - boolean holdingColor[] = new boolean[10]; - - /** - * Calls Renderscript functions (invoke_addParticles) - * via the Renderscript object to add particles to render - * based on where a user touches the screen. - */ - public void newTouchPosition(float x, float y, float pressure, int id) { - if (id >= holdingColor.length) { - return; - } - int rate = (int)(pressure * pressure * 500.f); - if (rate > 500) { - rate = 500; - } - if (rate > 0) { - mScript.invoke_addParticles(rate, x, y, id, !holdingColor[id]); - holdingColor[id] = true; - } else { - holdingColor[id] = false; - } - - } -} -</pre> - - - <h3 id="creating-view">Creating the view class</h3> - - - <p>To display graphics, you need a view to render on. Create a class that extends {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. This class - allows you to create a {@link android.renderscript.RenderScriptGL} context object by calling and - pass it to the Rendscript entry point class to bind the two. Once bound, the content is aware - of the code that it needs to use to render graphics with. If your Renderscript code - depends on any type of information that the view is aware of, such as touches from the user, - you can also use this class to relay that information to the Renderscript entry point class. - The following code shows how the <code>FountainView</code> class is implemented:</p> - <pre> -package com.example.android.rs.fountain; - -import android.renderscript.RSTextureView; -import android.renderscript.RenderScriptGL; -import android.content.Context; -import android.view.MotionEvent; - -public class FountainView extends RSTextureView { - - public FountainView(Context context) { - super(context); - } - // Renderscript context - private RenderScriptGL mRS; - // Renderscript entry point object that calls Renderscript code - private FountainRS mRender; - - /** - * Create Renderscript context and initialize Renderscript entry point - */ - @Override - protected void onAttachedToWindow() { - super.onAttachedToWindow(); - android.util.Log.e("rs", "onAttachedToWindow"); - if (mRS == null) { - RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig(); - mRS = createRenderScriptGL(sc); - mRender = new FountainRS(); - mRender.init(mRS, getResources()); - } - } - - @Override - protected void onDetachedFromWindow() { - super.onDetachedFromWindow(); - android.util.Log.e("rs", "onDetachedFromWindow"); - if (mRS != null) { - mRS = null; - destroyRenderScriptGL(); - } - } - - - /** - * Use callbacks to relay data to Renderscript entry point class - */ - @Override - public boolean onTouchEvent(MotionEvent ev) - { - int act = ev.getActionMasked(); - if (act == ev.ACTION_UP) { - mRender.newTouchPosition(0, 0, 0, ev.getPointerId(0)); - return false; - } else if (act == MotionEvent.ACTION_POINTER_UP) { - // only one pointer going up, we can get the index like this - int pointerIndex = ev.getActionIndex(); - int pointerId = ev.getPointerId(pointerIndex); - mRender.newTouchPosition(0, 0, 0, pointerId); - } - int count = ev.getHistorySize(); - int pcount = ev.getPointerCount(); - - for (int p=0; p < pcount; p++) { - int id = ev.getPointerId(p); - mRender.newTouchPosition(ev.getX(p), - ev.getY(p), - ev.getPressure(p), - id); - - for (int i=0; i < count; i++) { - mRender.newTouchPosition(ev.getHistoricalX(p, i), - ev.getHistoricalY(p, i), - ev.getHistoricalPressure(p, i), - id); - } - } - return true; - } -} -</pre> - - <h3 id="creating-activity">Creating the activity class</h3> - - <p>Applications that use Renderscript still behave like normal Android applications, so you - need an activity class that handles activity lifecycle callback events appropriately. The activity class - also sets your {@link android.renderscript.RSSurfaceView} view class to be the main content view of the - activity or uses your {@link android.renderscript.RSTextureView} - in a {@link android.view.ViewGroup} alongside other views.</p> - - <p>The following code shows how the <a href="{@docRoot}resources/samples/RenderScript/Fountain/index.html">Fountain</a> - sample declares its activity class:</p> - <pre> -package com.example.android.rs.fountain; - -import android.app.Activity; -import android.os.Bundle; -import android.util.Log; - -public class Fountain extends Activity { - - private static final String LOG_TAG = "libRS_jni"; - private static final boolean DEBUG = false; - private static final boolean LOG_ENABLED = false; - - private FountainView mView; - - @Override - public void onCreate(Bundle icicle) { - super.onCreate(icicle); - - // Create our Preview view and set it as - // the content of our activity - mView = new FountainView(this); - setContentView(mView); - } - - @Override - protected void onResume() { - Log.e("rs", "onResume"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onResume(); - mView.resume(); - } - - @Override - protected void onPause() { - Log.e("rs", "onPause"); - - // Ideally a game should implement onResume() and onPause() - // to take appropriate action when the activity looses focus - super.onPause(); - mView.pause(); - - } - - static void log(String message) { - if (LOG_ENABLED) { - Log.v(LOG_TAG, message); - } - } -} -</pre> - -<p>Now that you have an idea of what is involved in a Renderscript graphics application, you can -start building your own. It might be easiest to begin with one of the -<a href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript samples</a> as a starting -point if this is your first time using Renderscript.</p> - - <h2 id="drawing">Drawing</h2> - <p>The following sections describe how to use the graphics functions to draw with Renderscript.</p> - - <h3 id="drawing-rsg">Simple drawing</h3> - - <p>The native Renderscript APIs provide a few convenient functions to easily draw a polygon or text to - the screen. You call these in your <code>root()</code> function to have them render to the {@link - android.renderscript.RSSurfaceView} or {@link android.renderscript.RSTextureView}. These functions are - available for simple drawing and should not be used for complex graphics rendering:</p> - - <ul> - <li><code>rsgDrawRect()</code>: Sets up a mesh and draws a rectangle to the screen. It uses the - top left vertex and bottom right vertex of the rectangle to draw.</li> - - <li><code>rsgDrawQuad()</code>: Sets up a mesh and draws a quadrilateral to the screen.</li> - - <li><code>rsgDrawQuadTexCoords()</code>: Sets up a mesh and draws a quadrilateral to the screen - using the provided coordinates of a texture.</li> - - <li><code>rsgDrawText()</code>: Draws specified text to the screen. Use <code>rsgFontColor()</code> - to set the color of the text.</li> - </ul> - - <h3 id="drawing-mesh">Drawing with a mesh</h3> - - <p>When you want to render complex scenes to the screen, instantiate a {@link - android.renderscript.Mesh} and draw it with <code>rsgDrawMesh()</code>. A {@link - android.renderscript.Mesh} is a collection of allocations that represent vertex data (positions, - normals, texture coordinates) and index data that provides information on how to draw triangles - and lines with the provided vertex data. You can build a Mesh in three different ways:</p> - - <ul> - <li>Build the mesh with the {@link android.renderscript.Mesh.TriangleMeshBuilder} class, which - allows you to specify a set of vertices and indices for each triangle that you want to draw.</li> - - <li>Build the mesh using an {@link android.renderscript.Allocation} or a set of {@link - android.renderscript.Allocation}s with the {@link android.renderscript.Mesh.AllocationBuilder} - class. This approach allows you to build a mesh with vertices already stored in memory, which allows you - to specify the vertices in Renderscript or Android framework code.</li> - - <li>Build the mesh with the {@link android.renderscript.Mesh.Builder} class. You should use - this convenience method when you know the data types you want to use to build your mesh, but - don't want to make separate memory allocations like with {@link - android.renderscript.Mesh.AllocationBuilder}. You can specify the types that you want and this - mesh builder automatically creates the memory allocations for you.</li> - </ul> - - <p>To create a mesh using the {@link android.renderscript.Mesh.TriangleMeshBuilder}, you need to - supply it with a set of vertices and the indices for the vertices that comprise the triangle. For - example, the following code specifies three vertices, which are added to an internal array, - indexed in the order they were added. The call to {@link - android.renderscript.Mesh.TriangleMeshBuilder#addTriangle addTriangle()} draws the triangle with - vertex 0, 1, and 2 (the vertices are drawn counter-clockwise).</p> - <pre> -int float2VtxSize = 2; -Mesh.TriangleMeshBuilder triangles = new Mesh.TriangleMeshBuilder(renderscriptGL, -float2VtxSize, Mesh.TriangleMeshBuilder.COLOR); -triangles.addVertex(300.f, 300.f); -triangles.addVertex(150.f, 450.f); -triangles.addVertex(450.f, 450.f); -triangles.addTriangle(0 , 1, 2); -Mesh smP = triangle.create(true); -script.set_mesh(smP); -</pre> - - <p>To draw a mesh using the {@link android.renderscript.Mesh.AllocationBuilder}, you need to - supply it with one or more allocations that contain the vertex data:</p> - <pre> -Allocation vertices; - -... -Mesh.AllocationBuilder triangle = new Mesh.AllocationBuilder(mRS); -smb.addVertexAllocation(vertices.getAllocation()); -smb.addIndexSetType(Mesh.Primitive.TRIANGLE); -Mesh smP = smb.create(); -script.set_mesh(smP); -</pre> - - <p>In your Renderscript code, draw the built mesh to the screen:</p> - <pre> -rs_mesh mesh; -... - -int root(){ -... -rsgDrawMesh(mesh); -... -return 0; //specify a non zero, positive integer to specify the frame refresh. - //0 refreshes the frame only when the mesh changes. -} -</pre> - - <h2 id="shader">Programs</h2> - - <p>You can attach four program objects to the {@link android.renderscript.RenderScriptGL} context - to customize the rendering pipeline. For example, you can create vertex and fragment shaders in - GLSL or build a raster program object that controls culling. The four programs mirror a - traditional graphical rendering pipeline:</p> - - <table> - <tr> - <th>Android Object Type</th> - - <th>Renderscript Native Type</th> - - <th>Description</th> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramVertex}</td> - - <td>rs_program_vertex</td> - - <td> - <p>The Renderscript vertex program, also known as a vertex shader, describes the stage in - the graphics pipeline responsible for manipulating geometric data in a user-defined way. - The object is constructed by providing Renderscript with the following data:</p> - - <ul> - <li>An {@link android.renderscript.Element} describing its varying inputs or attributes</li> - - <li>GLSL shader string that defines the body of the program</li> - - <li>a {@link android.renderscript.Type} that describes the layout of an - Allocation containing constant or uniform inputs</li> - </ul> - - <p>Once the program is created, bind it to the {@link android.renderscript.RenderScriptGL} - graphics context by calling {@link android.renderscript.RenderScriptGL#bindProgramVertex - bindProgramVertex()}. It is then used for all subsequent draw calls until you bind a new - program. If the program has constant inputs, the user needs to bind an allocation - containing those inputs. The allocation's type must match the one provided during creation. - </p> - - <p>The Renderscript runtime then does all the necessary plumbing to send those constants to - the graphics hardware. Varying inputs to the shader, such as position, normal, and texture - coordinates are matched by name between the input {@link android.renderscript.Element} - and the mesh object that is being drawn. The signatures don't have to be exact or in any - strict order. As long as the input name in the shader matches a channel name and size - available on the mesh, the Renderscript runtime handles connecting the two. Unlike OpenGL - there is no need to link the vertex and fragment programs.</p> - - <p>To bind shader constants to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramVertexFixedFunction.Builder} class also - lets you build a simple vertex shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramFragment}</td> - - <td>rs_program_fragment</td> - - <td> - <p>The Renderscript fragment program, also known as a fragment shader, is responsible for - manipulating pixel data in a user-defined way. It's constructed from a GLSL shader string - containing the program body, texture inputs, and a {@link android.renderscript.Type} - object that describes the constants - used by the program. Like the vertex programs, when an {@link android.renderscript.Allocation} - with constant input - values is bound to the shader, its values are sent to the graphics program automatically. - Note that the values inside the {@link android.renderscript.Allocation} are not explicitly tracked. - If they change between two draw calls using the same program object, notify the runtime of that change by - calling <code>rsgAllocationSyncAll()</code>, so it can send the new values to hardware. Communication - between the vertex and fragment programs is handled internally in the GLSL code. For - example, if the fragment program is expecting a varying input called <code>varTex0</code>, the GLSL code - inside the program vertex must provide it.</p> - - <p>To bind shader constructs to the program, declare a <code>struct</code> that contains the necessary - shader constants in your Renderscript code. This <code>struct</code> is generated into a - reflected class that you can use as a constant input element during the program's creation. - It is an easy way to create an instance of this <code>struct</code> as an allocation. You would then - bind this {@link android.renderscript.Allocation} to the program and the - Renderscript runtime sends the data that is contained in the <code>struct</code> to the hardware - when necessary. To update shader constants, you change the values in the - {@link android.renderscript.Allocation} and notify the Renderscript - code of the change.</p> - - <p>The {@link android.renderscript.ProgramFragmentFixedFunction.Builder} class also - lets you build a simple fragment shader without writing GLSL code. - </p> - </td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramStore}</td> - - <td>rs_program_store</td> - - <td>The Renderscript store program contains a set of parameters that control how the graphics - hardware writes to the framebuffer. It could be used to enable and disable depth writes and - testing, setup various blending modes for effects like transparency and define write masks - for color components.</td> - </tr> - - <tr> - <td>{@link android.renderscript.ProgramRaster}</td> - - <td>rs_program_raster</td> - - <td>The Renderscript raster program is primarily used to specify whether point sprites are enabled and to - control the culling mode. By default back faces are culled.</td> - </tr> - </table> - - <p>The following example defines a vertex shader in GLSL and binds it to a Renderscript context object:</p> - <pre> - private RenderScriptGL glRenderer; //rendering context - private ScriptField_Point mPoints; //vertices - private ScriptField_VpConsts mVpConsts; //shader constants - - ... - - ProgramVertex.Builder sb = new ProgramVertex.Builder(glRenderer); - String t = "varying vec4 varColor;\n" + - "void main() {\n" + - " vec4 pos = vec4(0.0, 0.0, 0.0, 1.0);\n" + - " pos.xy = ATTRIB_position;\n" + - " gl_Position = UNI_MVP * pos;\n" + - " varColor = vec4(1.0, 1.0, 1.0, 1.0);\n" + - " gl_PointSize = ATTRIB_size;\n" + - "}\n"; - sb.setShader(t); - sb.addConstant(mVpConsts.getType()); - sb.addInput(mPoints.getElement()); - ProgramVertex pvs = sb.create(); - pvs.bindConstants(mVpConsts.getAllocation(), 0); - glRenderer.bindProgramVertex(pvs); -</pre> - - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a shader without writing GLSL.</p> - - <h3 id="shader-bindings">Program bindings</h3> - - <p>You can also declare four pragmas that control default program bindings to the {@link - android.renderscript.RenderScriptGL} context when the script is executing:</p> - - <ul> - <li><code>stateVertex</code></li> - - <li><code>stateFragment</code></li> - - <li><code>stateRaster</code></li> - - <li><code>stateStore</code></li> - </ul> - - <p>The possible values for each pragma are <code>parent</code> or <code>default</code>. Using - <code>default</code> binds the shaders to the graphical context with the system defaults.</p> - - <p>Using <code>parent</code> binds the shaders in the same manner as it is bound in the calling - script. If this is the root script, the parent state is taken from the bind points that are set - by the {@link android.renderscript.RenderScriptGL} bind methods.</p> - - <p>For example, you can define this at the top of your graphics Renderscript code to have - the vertex and store programs inherent the bind properties from their parent scripts:</p> - <pre> -#pragma stateVertex(parent) -#pragma stateStore(parent) -</pre> - - <h3 id="shader-sampler">Defining a sampler</h3> - - <p>A {@link android.renderscript.Sampler} object defines how data is extracted from textures. - Samplers are bound to a {@link android.renderscript.ProgramFragment} alongside the texture - whose sampling they control. These - objects are used to specify such things as edge clamping behavior, whether mip-maps are used, and - the amount of anisotropy required. There might be situations where hardware does not support the - desired behavior of the sampler. In these cases, the Renderscript runtime attempts to provide the - closest possible approximation. For example, the user requested 16x anisotropy, but only 8x was - set because it's the best available on the hardware.</p> - - <p>The <a href= - "{@docRoot}resources/samples/RenderScript/MiscSamples/src/com/example/android/rs/miscsamples/RsRenderStatesRS.html"> - RsRenderStatesRS</a> sample has many examples on how to create a sampler and bind it to a - Fragment program.</p> - - - -<h2 id="fbo">Rendering to a Framebuffer Object</h2> - -<p>Framebuffer objects allow you to render offscreen instead of in the default onscreen -framebuffer. This approach might be useful for situations where you need to post-process a texture before -rendering it to the screen, or when you want to composite two scenes in one such as rendering a rear-view -mirror of a car. There are two buffers associated with a framebuffer object: a color buffer -and a depth buffer. The color buffer (required) contains the actual pixel data of the scene -that you are rendering, and the depth buffer (optional) contains the values necessary to figure -out what vertices are drawn depending on their z-values.</p> - -<p>In general, you need to do the following to render to a framebuffer object:</p> - -<ul> - <li>Create {@link android.renderscript.Allocation} objects for the color buffer and - depth buffer (if needed). Specify the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_RENDER_TARGET} usage attribute for these - allocations to notify the Renderscript runtime to use these allocations for the framebuffer - object. For the color buffer allocation, you most likely need to declare the {@link - android.renderscript.Allocation#USAGE_GRAPHICS_TEXTURE} usage attribute - to use the color buffer as a texture, which is the most common use of the framebuffer object.</li> - - <li>Tell the Renderscript runtime to render to the framebuffer object instead of the default - framebuffer by calling <code>rsgBindColorTarget()</code> and passing it the color buffer - allocation. If applicable, call <code>rsgBindDepthTarget()</code> passing in the depth buffer - allocation as well.</li> - - <li>Render your scene normally with the <code>rsgDraw</code> functions. The scene will be - rendered into the color buffer instead of the default onscreen framebuffer.</li> - - <li>When done, tell the Renderscript runtime stop rendering to the color buffer and back - to the default framebuffer by calling <code>rsgClearAllRenderTargets()</code>.</li> - - <li>Create a fragment shader and bind a the color buffer to it as a texture.</li> - - <li>Render your scene to the default framebuffer. The texture will be used according - to the way you setup your fragment shader.</li> -</ul> - -<p>The following example shows you how to render to a framebuffer object by modifying the -<a href="{@docRoot}guide/resources/renderscript/Fountain/">Fountain</a> Renderscript sample. The end -result is the <a href="{@docRoot}guide/resources/renderscript/FountainFBO/">FountainFBO</a> sample. -The modifications render the exact same scene into a framebuffer object as it does the default -framebuffer. The framebuffer object is then rendered into the default framebuffer in a small -area at the top left corner of the screen.</p> - -<ol> - <li>Modify <code>fountain.rs</code> and add the following global variables. This creates setter - methods when this file is reflected into a <code>.java</code> file, allowing you to allocate - memory in your Android framework code and binding it to the Renderscript runtime. -<pre> -//allocation for color buffer -rs_allocation gColorBuffer; -//fragment shader for rendering without a texture (used for rendering to framebuffer object) -rs_program_fragment gProgramFragment; -//fragment shader for rendering with a texture (used for rendering to default framebuffer) -rs_program_fragment gTextureProgramFragment; -</pre> - </li> - - <li>Modify the root function of <code>fountain.rs</code> to look like the following code. The - modifications are commented: -<pre> -int root() { - float dt = min(rsGetDt(), 0.1f); - rsgClearColor(0.f, 0.f, 0.f, 1.f); - const float height = rsgGetHeight(); - const int size = rsAllocationGetDimX(rsGetAllocation(point)); - float dy2 = dt * (10.f); - Point_t * p = point; - for (int ct=0; ct < size; ct++) { - p->delta.y += dy2; - p->position += p->delta; - if ((p->position.y > height) && (p->delta.y > 0)) { - p->delta.y *= -0.3f; - } - p++; - } - //Tell Renderscript runtime to render to the frame buffer object - rsgBindColorTarget(gColorBuffer, 0); - //Begin rendering on a white background - rsgClearColor(1.f, 1.f, 1.f, 1.f); - rsgDrawMesh(partMesh); - - //When done, tell Renderscript runtime to stop rendering to framebuffer object - rsgClearAllRenderTargets(); - - //Bind a new fragment shader that declares the framebuffer object to be used as a texture - rsgBindProgramFragment(gTextureProgramFragment); - - //Bind the framebuffer object to the fragment shader at slot 0 as a texture - rsgBindTexture(gTextureProgramFragment, 0, gColorBuffer); - //Draw a quad using the framebuffer object as the texture - float startX = 10, startY = 10; - float s = 256; - rsgDrawQuadTexCoords(startX, startY, 0, 0, 1, - startX, startY + s, 0, 0, 0, - startX + s, startY + s, 0, 1, 0, - startX + s, startY, 0, 1, 1); - - //Rebind the original fragment shader to render as normal - rsgBindProgramFragment(gProgramFragment); - - //Render the main scene - rsgDrawMesh(partMesh); - - return 1; -} -</pre> - </li> - - <li>In the <code>FountainRS.java</code> file, modify the <code>init()</code> method to look - like the following code. The modifications are commented: - -<pre> -/* Add necessary members */ -private ScriptC_fountainfbo mScript; -private Allocation mColorBuffer; -private ProgramFragment mProgramFragment; -private ProgramFragment mTextureProgramFragment; - -public void init(RenderScriptGL rs, Resources res) { - mRS = rs; - mRes = res; - - ScriptField_Point points = new ScriptField_Point(mRS, PART_COUNT); - - Mesh.AllocationBuilder smb = new Mesh.AllocationBuilder(mRS); - smb.addVertexAllocation(points.getAllocation()); - smb.addIndexSetType(Mesh.Primitive.POINT); - Mesh sm = smb.create(); - - mScript = new ScriptC_fountainfbo(mRS, mRes, R.raw.fountainfbo); - mScript.set_partMesh(sm); - mScript.bind_point(points); - - ProgramFragmentFixedFunction.Builder pfb = new ProgramFragmentFixedFunction.Builder(rs); - pfb.setVaryingColor(true); - mProgramFragment = pfb.create(); - mScript.set_gProgramFragment(mProgramFragment); - - /* Second fragment shader to use a texture (framebuffer object) to draw with */ - pfb.setTexture(ProgramFragmentFixedFunction.Builder.EnvMode.REPLACE, - ProgramFragmentFixedFunction.Builder.Format.RGBA, 0); - - /* Set the fragment shader in the Renderscript runtime */ - mTextureProgramFragment = pfb.create(); - mScript.set_gTextureProgramFragment(mTextureProgramFragment); - - /* Create the allocation for the color buffer */ - Type.Builder colorBuilder = new Type.Builder(mRS, Element.RGBA_8888(mRS)); - colorBuilder.setX(256).setY(256); - mColorBuffer = Allocation.createTyped(mRS, colorBuilder.create(), - Allocation.USAGE_GRAPHICS_TEXTURE | - Allocation.USAGE_GRAPHICS_RENDER_TARGET); - - /* Set the allocation in the Renderscript runtime */ - mScript.set_gColorBuffer(mColorBuffer); - - mRS.bindRootScript(mScript); -} -</pre> - -<p class="note"><strong>Note:</strong> This sample doesn't use a depth buffer, but the following code -shows you how to declare an example depth buffer if you need to use -one for your application. The depth buffer must have the same dimensions as the color buffer: - -<pre> -Allocation mDepthBuffer; - -... - -Type.Builder b = new Type.Builder(mRS, Element.createPixel(mRS, DataType.UNSIGNED_16, - DataKind.PIXEL_DEPTH)); -b.setX(256).setY(256); -mDepthBuffer = Allocation.createTyped(mRS, b.create(), -Allocation.USAGE_GRAPHICS_RENDER_TARGET); - -</pre> -</p> -</li> - - <li>Run and use the sample. The smaller, white quad on the top-left corner is using the - framebuffer object as a texture, which renders the same scene as the main rendering.</li> -</ol> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index c9f505f..adc795d 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -27,11 +27,13 @@ parent.link=manifest-intro.html android:<a href="#parent">parentActivityName</a>="<i>string</i>" <!-- api level 16 --> android:<a href="#prmsn">permission</a>="<i>string</i>" android:<a href="#proc">process</a>="<i>string</i>" - android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" | + android:<a href="#screen">screenOrientation</a>=["unspecified" | "behind" | "landscape" | "portrait" | "reverseLandscape" | "reversePortrait" | "sensorLandscape" | "sensorPortrait" | - "sensor" | "fullSensor" | "nosensor"] + "userLandscape" | "userPortrait" | + "sensor" | "fullSensor" | "nosensor" | + "user" | "fullUser" | "locked"] android:<a href="#state">stateNotNeeded</a>=["true" | "false"] android:<a href="#aff">taskAffinity</a>="<i>string</i>" android:<a href="#theme">theme</a>="<i>resource or theme</i>" @@ -644,9 +646,6 @@ resource usage. uses, and therefore the choices made in specific contexts, may differ from device to device.</td> </tr><tr> - <td>"{@code user}"</td> - <td>The user's current preferred orientation.</td> -</tr><tr> <td>"{@code behind}"</td> <td>The same orientation as the activity that's immediately beneath it in the activity stack.</td> @@ -675,6 +674,18 @@ sensor. sensor. <em>Added in API level 9.</em></td> </tr><tr> + <td>"{@code userLandscape}"</td> + <td>Landscape orientation, but can be either normal or reverse landscape based on the device +sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves +the same as {@code landscape}, otherwise it behaves the same as {@code sensorLandscape}. +<em>Added in API level 18.</em></td> +</tr><tr> + <td>"{@code userPortrait}"</td> + <td>Portrait orientation, but can be either normal or reverse portrait based on the device +sensor and the user's sensor preference. If the user has locked sensor-based rotation, this behaves +the same as {@code portrait}, otherwise it behaves the same as {@code sensorPortrait}. +<em>Added in API level 18.</em></td> +</tr><tr> <td>"{@code sensor}"</td> <td>The orientation is determined by the device orientation sensor. The orientation of the display depends on how the user is holding the device; it changes when the user rotates the @@ -692,6 +703,19 @@ portrait or reverse landscape, but this enables those). <em>Added in API level 9 is ignored, so the display will not rotate based on how the user moves the device. Except for this distinction, the system chooses the orientation using the same policy as for the "{@code unspecified}" setting.</td> +</tr><tr> + <td>"{@code user}"</td> + <td>The user's current preferred orientation.</td> +</tr><tr> + <td>"{@code fullUser}"</td> + <td>If the user has locked sensor-based rotation, this behaves the same as {@code user}, + otherwise it behaves the same as {@code fullSensor} and allows any of the 4 possible + screen orientations. + <em>Added in API level 18.</em></td> +</tr><tr> + <td>"{@code locked}"</td> + <td>Locks the orientation to its current rotation, whatever that is. +<em>Added in API level 18.</em></td> </tr> </table> diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 42cfdd5..6bfa3dc 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -1,11 +1,11 @@ page.title=<application> -parent.title=The AndroidManifest.xml File -parent.link=manifest-intro.html + @jd:body <dl class="xml"> <dt>syntax:</dt> <dd><pre class="stx"><application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] + android:<a href="#allowbackup">allowBackup</a>=["true" | "false"] android:<a href="#agent">backupAgent</a>="<i>string</i>" android:<a href="#debug">debuggable</a>=["true" | "false"] android:<a href="#desc">description</a>="<i>string resource</i>" @@ -23,10 +23,14 @@ parent.link=manifest-intro.html android:<a href="#persistent">persistent</a>=["true" | "false"] android:<a href="#proc">process</a>="<i>string</i>" android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"] + android:<a href="#requiredAccountType">requiredAccountType</a>="<i>string</i>" + android:<a href="#restrictedAccountType">restrictedAccountType</a>="<i>string</i>" android:<a href="#supportsrtl">supportsRtl</a>=["true" | "false"] android:<a href="#aff">taskAffinity</a>="<i>string</i>" + android:<a href="#testOnly">testOnly</a>=["true" | "false"] android:<a href="#theme">theme</a>="<i>resource or theme</i>" - android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] > + android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] + android:<a href="#vmSafeMode">vmSafeMode</a>=["true" | "false"] > . . . </application></pre></dd> @@ -52,6 +56,10 @@ for corresponding attributes of the component elements. Others (such as {@code allowClearUserData}) set values for the application as a whole and cannot be overridden by the components.</dd> + + + + <dt>attributes</dt> <dd><dl class="attr"> @@ -71,6 +79,15 @@ attribute that can override the value set here. See that attribute for more information. </p></dd> + +<dt><a name="allowbackup"></a>{@code android:allowbackup}</dt> +<dd>Whether to allow the application to participate in the backup +and restore infrastructure. If this attribute is set to false, no backup +or restore of the application will ever be performed, even by a full-system +backup that would otherwise cause all application data to be saved via adb. +The default value of this attribute is true.</dd> + + <dt><a name="agent"></a>{@code android:backupAgent}</dt> <dd>The name of the class that implement's the application's backup agent, a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be @@ -282,6 +299,57 @@ incompatible. <em>Use with caution!</em> <p>The default value of this attribute is {@code false}. </p></dd> + + +<dt><a name="requiredAccountType"></a>{@code android:requiredAccountType}</dt> +<dd>Specifies the account type required by the application in order to function. +If your app requires an {@link android.accounts.Account}, the value for this attribute must +correspond to the account authenticator +type used by your app (as defined by {@link android.accounts.AuthenticatorDescription}), +such as "com.google". + +<p>The default value is null and indicates that the application +can work <em>without</em> any accounts. + +<p>Because restricted profiles currently +cannot add accounts, specifying this attribute <strong>makes your app +unavailable from a restricted profile</strong> unless you also declare +<a href="#restrictedAccountType">{@code android:restrictedAccountType}</a> with +the same value.</p> + +<p class="caution"><strong>Caution:</strong> +If the account data may reveal personally identifiable information, it's important +that you declare this attribute and leave <a href="#restrictedAccountType">{@code android:restrictedAccountType}</a> null, so that restricted profiles cannot use +your app to access personal information that belongs to the owner user.</p> + +<p>This attribute was added in API level 18.</p> +</dd> + + +<dt><a name="restrictedAccountType"></a>{@code android:restrictedAccountType}</dt> +<dd>Specifies the account type required by this application and indicates that restricted profiles +are allowed to access such accounts that belong to the owner user. If your app requires an +{@link android.accounts.Account} and restricted profiles <strong>are allowed to +access</strong> the primary user's accounts, the value for this attribute must +correspond to the account authenticator type used by your app (as +defined by {@link android.accounts.AuthenticatorDescription}), such as "com.google". + +<p>The default value is null and indicates that the application can work <em>without</em> any +accounts. + +<p class="caution"><strong>Caution:</strong> +Specifying this attribute allows restricted profiles to use your +app with accounts that belong to the owner user, which may reveal personally identifiable +information. If the account may reveal personal details, you <strong>should not</strong> +use this attribute and you should instead declare the <a +href="#requiredAccountType">{@code android:requiredAccountType}</a> attribute +to make your app unavailable to restricted profiles.</p> + +<p>This attribute was added in API level 18.</p> +</dd> + + + <dt><a name="supportsrtl"></a>{@code android:supportsRtl}</dt> <dd>Declares whether your application is willing to support right-to-left (RTL) layouts. <p>If set to {@code true} and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" @@ -310,6 +378,13 @@ set by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p></dd> +<dt><a name="testOnly"></a>{@code android:testOnly}</dt> +<dd>Indicates whether this application is only for testing purposes. For example, +it may expose functionality or data outside of itself that would cause a security +hole, but is useful for testing. This kind of application can be installed +only through adb.</dd> + + <dt><a name="theme"></a>{@code android:theme}</dt> <dd>A reference to a style resource defining a default theme for all activities in the application. Individual activities can override @@ -340,6 +415,14 @@ href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.< <p>This attribute was added in API level 14.</p> </dd> +<dt><a name="vmSafeMode"></a>{@code android:vmSafeMode}</dt> +<dd>Indicates whether the app would like the virtual machine (VM) to operate +in safe mode. The default value is {@code "false"}. +</dd> + + + + </dl></dd> <!-- ##api level indication## --> diff --git a/docs/html/guide/topics/renderscript/advanced.jd b/docs/html/guide/topics/renderscript/advanced.jd index 58f5e1f..6a72b97 100644 --- a/docs/html/guide/topics/renderscript/advanced.jd +++ b/docs/html/guide/topics/renderscript/advanced.jd @@ -1,4 +1,4 @@ -page.title=Advanced Renderscript +page.title=Advanced RenderScript parent.title=Computation parent.link=index.html @@ -9,7 +9,7 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#native">Renderscript Runtime Layer</a></li> + <li><a href="#native">RenderScript Runtime Layer</a></li> <li><a href="#reflected">Reflected Layer</a> <ol> <li><a href="#func">Functions</a></li> @@ -25,7 +25,7 @@ parent.link=index.html <li> <a href="#memory">Working with Memory</a> <ol> - <li><a href="#allocating-mem">Allocating and binding memory to the Renderscript</a></li> + <li><a href="#allocating-mem">Allocating and binding memory to the RenderScript</a></li> <li><a href="#read-write">Reading and writing to memory</a></li> @@ -37,36 +37,36 @@ parent.link=index.html <p></p> - <p>Because applications that utilize Renderscript still run inside of the Android VM, + <p>Because applications that utilize RenderScript still run inside of the Android VM, you have access to all of the framework APIs that you are familiar with, but can - utilize Renderscript when appropriate. To facilitate this interaction between - the framework and the Renderscript runtime, an intermediate layer of code is also + utilize RenderScript when appropriate. To facilitate this interaction between + the framework and the RenderScript runtime, an intermediate layer of code is also present to facilitate communication and memory management between the two levels of code. This document goes into more detail about these different layers of code as well as how memory is shared between the Android VM and - Renderscript runtime.</p> + RenderScript runtime.</p> - <h2 id="native">Renderscript Runtime Layer</h2> + <h2 id="native">RenderScript Runtime Layer</h2> - <p>Your Renderscript code is compiled and - executed in a compact and well-defined runtime layer. The Renderscript runtime APIs offer support for + <p>Your RenderScript code is compiled and + executed in a compact and well-defined runtime layer. The RenderScript runtime APIs offer support for intensive computation that is portable and automatically scalable to the amount of cores available on a processor. </p> <p class="note"><strong>Note:</strong> The standard C functions in the NDK must be - guaranteed to run on a CPU, so Renderscript cannot access these libraries, - because Renderscript is designed to run on different types of processors.</p> + guaranteed to run on a CPU, so RenderScript cannot access these libraries, + because RenderScript is designed to run on different types of processors.</p> -<p>You define your Renderscript code in <code>.rs</code> +<p>You define your RenderScript code in <code>.rs</code> and <code>.rsh</code> files in the <code>src/</code> directory of your Android project. The code is compiled to intermediate bytecode by the <code>llvm</code> compiler that runs as part of an Android build. When your application runs on a device, the bytecode is then compiled (just-in-time) to machine code by another <code>llvm</code> compiler that resides on the device. The machine code is optimized for the - device and also cached, so subsequent uses of the Renderscript enabled application does not + device and also cached, so subsequent uses of the RenderScript enabled application does not recompile the bytecode.</p> - <p>Some key features of the Renderscript runtime libraries include:</p> + <p>Some key features of the RenderScript runtime libraries include:</p> <ul> @@ -79,20 +79,20 @@ amount of cores available on a processor. <li>Conversion routines for primitive data types and vectors, matrix routines, and date and time routines</li> - <li>Data types and structures to support the Renderscript system such as Vector types for + <li>Data types and structures to support the RenderScript system such as Vector types for defining two-, three-, or four-vectors.</li> <li>Logging functions</li> </ul> - <p>See the Renderscript runtime API reference for more information on the available functions. + <p>See the RenderScript runtime API reference for more information on the available functions. <h2 id="reflected">Reflected Layer</h2> <p>The reflected layer is a set of classes that the Android build tools generate to allow access - to the Renderscript runtime from the Android framework. This layer also provides methods + to the RenderScript runtime from the Android framework. This layer also provides methods and constructors that allow you to allocate and work with memory for pointers that are defined in -your Renderscript code. The following list describes the major +your RenderScript code. The following list describes the major components that are reflected:</p> <ul> @@ -105,9 +105,9 @@ following items reflected from the <code>.rs</code> file: <ul> <li>Non-static functions</li> - <li>Non-static, global Renderscript variables. Accessor methods are generated for each - variable, so you can read and write the Renderscript variables from the Android - framework. If a global variable is initialized at the Renderscript runtime layer, those + <li>Non-static, global RenderScript variables. Accessor methods are generated for each + variable, so you can read and write the RenderScript variables from the Android + framework. If a global variable is initialized at the RenderScript runtime layer, those values are used to initialize the corresponding values in the Android framework layer. If global variables are marked as <code>const</code>, then a <code>set</code> method is not generated.</p></li> @@ -128,7 +128,7 @@ generated.</p></li> <h3 id="func">Functions</h3> <p>Functions are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. For -example, if you declare the following function in your Renderscript code:</p> +example, if you declare the following function in your RenderScript code:</p> <pre> void touch(float x, float y, float pressure, int id) { @@ -155,14 +155,14 @@ public void invoke_touch(float x, float y, float pressure, int id) { } </pre> <p> -Functions cannot have a return value, because the Renderscript system is designed to be -asynchronous. When your Android framework code calls into Renderscript, the call is queued and is -executed when possible. This restriction allows the Renderscript system to function without constant +Functions cannot have a return value, because the RenderScript system is designed to be +asynchronous. When your Android framework code calls into RenderScript, the call is queued and is +executed when possible. This restriction allows the RenderScript system to function without constant interruption and increases efficiency. If functions were allowed to have return values, the call would block until the value was returned.</p> <p> -If you want the Renderscript code to send a value back to the Android framework, use the +If you want the RenderScript code to send a value back to the Android framework, use the <a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function. </p> @@ -172,7 +172,7 @@ function. <p>Variables of supported types are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. A set of accessor methods are generated for each variable. For example, if you declare the following variable in -your Renderscript code:</p> +your RenderScript code:</p> <pre>uint32_t unsignedInteger = 1;</pre> <p>then the following code is generated:</p> @@ -329,7 +329,7 @@ public class ScriptField_Point extends android.renderscript.Script.FieldBase { </pre> <p>The generated code is provided to you as a convenience to allocate memory for structs requested -by the Renderscript runtime and to interact with <code>struct</code>s +by the RenderScript runtime and to interact with <code>struct</code>s in memory. Each <code>struct</code>'s class defines the following methods and constructors:</p> <ul> @@ -356,11 +356,11 @@ in memory. Each <code>struct</code>'s class defines the following methods and co </ul> <p>You can specify multiple memory spaces by using the bitwise <code>OR</code> operator. Doing so - notifies the Renderscript runtime that you intend on accessing the data in the + notifies the RenderScript runtime that you intend on accessing the data in the specified memory spaces. The following example allocates memory for a custom data type in both the script and vertex memory spaces:</p> <pre> - ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2, + ScriptField_Point touchPoints = new ScriptField_Point(myRenderScript, 2, Allocation.USAGE_SCRIPT | Allocation.USAGE_GRAPHICS_VERTEX); </pre> </li> @@ -370,13 +370,13 @@ in memory. Each <code>struct</code>'s class defines the following methods and co with the <code>struct</code> in your Android code. When you are done manipulating the object, you can push the object to the allocated memory by calling <code>set(Item i, int index, boolean copyNow)</code> and setting the <code>Item</code> to the desired position in -the array. The Renderscript runtime automatically has access to the newly written memory. +the array. The RenderScript runtime automatically has access to the newly written memory. <li>Accessor methods to get and set the values of each field in a struct. Each of these accessor methods have an <code>index</code> parameter to specify the <code>struct</code> in the array that you want to read or write to. Each setter method also has a <code>copyNow</code> parameter that specifies whether or not to immediately sync this memory -to the Renderscript runtime. To sync any memory that has not been synced, call +to the RenderScript runtime. To sync any memory that has not been synced, call <code>copyAll()</code>.</li> <li>The <code>createElement()</code> method creates a description of the struct in memory. This @@ -387,7 +387,7 @@ expand previously allocated memory, maintaining the current values that were pre created.</li> <li><code>copyAll()</code> synchronizes memory that was set on the framework level to the -Renderscript runtime. When you call a set accessor method on a member, there is an optional +RenderScript runtime. When you call a set accessor method on a member, there is an optional <code>copyNow</code> boolean parameter that you can specify. Specifying <code>true</code> synchronizes the memory when you call the method. If you specify false, you can call <code>copyAll()</code> once, and it synchronizes memory for all the @@ -397,7 +397,7 @@ properties that are not yet synchronized.</li> <h3 id="pointer">Pointers</h3> <p>Pointers are reflected into the script class itself, located in <code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You -can declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a +can declare pointers to a <code>struct</code> or any of the supported RenderScript types, but a <code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the following pointers to a <code>struct</code> and <code>int32_t</code></p> @@ -438,7 +438,7 @@ public Allocation get_intPointer() { <p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> (instead of a <code>set()</code> method) is generated. This method allows you to bind the memory -that is allocated in the Android VM to the Renderscript runtime (you cannot allocate +that is allocated in the Android VM to the RenderScript runtime (you cannot allocate memory in your <code>.rs</code> file). For more information, see <a href="#memory">Working with Allocated Memory</a>. </p> @@ -446,14 +446,14 @@ with Allocated Memory</a>. <h2 id="mem-allocation">Memory Allocation APIs</h2> - <p>Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and + <p>Applications that use RenderScript still run in the Android VM. The actual RenderScript code, however, runs natively and needs access to the memory allocated in the Android VM. To accomplish this, you must - attach the memory that is allocated in the VM to the Renderscript runtime. This -process, called binding, allows the Renderscript runtime to seamlessly work with memory that it + attach the memory that is allocated in the VM to the RenderScript runtime. This +process, called binding, allows the RenderScript runtime to seamlessly work with memory that it requests but cannot explicitly allocate. The end result is essentially the same as if you had called <code>malloc</code> in C. The added benefit is that the Android VM can carry out garbage collection as well as -share memory with the Renderscript runtime layer. Binding is only necessary for dynamically allocated memory. Statically -allocated memory is automatically created for your Renderscript code at compile time. See <a href="#figure1">Figure 1</a> +share memory with the RenderScript runtime layer. Binding is only necessary for dynamically allocated memory. Statically +allocated memory is automatically created for your RenderScript code at compile time. See <a href="#figure1">Figure 1</a> for more information on how memory allocation occurs. </p> @@ -479,11 +479,11 @@ understand how these classes work, it is useful to think of them in relation to <p>In most situations, you do not need to call these memory allocation APIs directly. The reflected layer classes generate code to use these APIs automatically and all you need to do to allocate memory is call a constructor that is declared in one of the reflected layer classes and then bind - the resulting memory {@link android.renderscript.Allocation} to the Renderscript. + the resulting memory {@link android.renderscript.Allocation} to the RenderScript. There are some situations where you would want to use these classes directly to allocate memory on your own, such as loading a bitmap from a resource or when you want to allocate memory for pointers to primitive types. You can see how to do this in the - <a href="#allocating-mem">Allocating and binding memory to the Renderscript</a> section. + <a href="#allocating-mem">Allocating and binding memory to the RenderScript</a> section. The following table describes the three memory management classes in more detail:</p> <table id="mem-mgmt-table"> @@ -500,12 +500,12 @@ understand how these classes work, it is useful to think of them in relation to <p>An element describes one cell of a memory allocation and can have two forms: basic or complex.</p> - <p>A basic element contains a single component of data of any valid Renderscript data type. + <p>A basic element contains a single component of data of any valid RenderScript data type. Examples of basic element data types include a single <code>float</code> value, a <code>float4</code> vector, or a single RGB-565 color.</p> <p>Complex elements contain a list of basic elements and are created from - <code>struct</code>s that you declare in your Renderscript code. For instance an allocation + <code>struct</code>s that you declare in your RenderScript code. For instance an allocation can contain multiple <code>struct</code>s arranged in order in memory. Each struct is considered as its own element, rather than each data type within that struct.</p> </td> @@ -552,64 +552,64 @@ understand how these classes work, it is useful to think of them in relation to <h2 id="memory">Working with Memory</h2> -<p>Non-static, global variables that you declare in your Renderscript are allocated memory at compile time. -You can work with these variables directly in your Renderscript code without having to allocate +<p>Non-static, global variables that you declare in your RenderScript are allocated memory at compile time. +You can work with these variables directly in your RenderScript code without having to allocate memory for them at the Android framework level. The Android framework layer also has access to these variables with the provided accessor methods that are generated in the reflected layer classes. If these variables are -initialized at the Renderscript runtime layer, those values are used to initialize the corresponding +initialized at the RenderScript runtime layer, those values are used to initialize the corresponding values in the Android framework layer. If global variables are marked as const, then a <code>set</code> method is not generated.</p> -<p class="note"><strong>Note:</strong> If you are using certain Renderscript structures that contain pointers, such as +<p class="note"><strong>Note:</strong> If you are using certain RenderScript structures that contain pointers, such as <code>rs_program_fragment</code> and <code>rs_allocation</code>, you have to obtain an object of the corresponding Android framework class first and then call the <code>set</code> method for that -structure to bind the memory to the Renderscript runtime. You cannot directly manipulate these structures -at the Renderscript runtime layer. This restriction is not applicable to user-defined structures +structure to bind the memory to the RenderScript runtime. You cannot directly manipulate these structures +at the RenderScript runtime layer. This restriction is not applicable to user-defined structures that contain pointers, because they cannot be exported to a reflected layer class in the first place. A compiler error is generated if you try to declare a non-static, global struct that contains a pointer. </p> -<p>Renderscript also has support for pointers, but you must explicitly allocate the memory in your +<p>RenderScript also has support for pointers, but you must explicitly allocate the memory in your Android framework code. When you declare a global pointer in your <code>.rs</code> file, you allocate memory through the appropriate reflected layer class and bind that memory to the native -Renderscript layer. You can interact with this memory from the Android framework layer as well as -the Renderscript layer, which offers you the flexibility to modify variables in the most +RenderScript layer. You can interact with this memory from the Android framework layer as well as +the RenderScript layer, which offers you the flexibility to modify variables in the most appropriate layer.</p> - <h3 id="allocating-mem">Allocating and binding dynamic memory to the Renderscript</h3> + <h3 id="allocating-mem">Allocating and binding dynamic memory to the RenderScript</h3> <p>To allocate dynamic memory, you need to call the constructor of a {@link android.renderscript.Script.FieldBase} class, which is the most common way. An alternative is to create an {@link android.renderscript.Allocation} manually, which is required for things such as primitive type pointers. You should use a {@link android.renderscript.Script.FieldBase} class constructor whenever available for simplicity. After obtaining a memory allocation, call the reflected <code>bind</code> method of the pointer to bind the allocated memory to the - Renderscript runtime.</p> + RenderScript runtime.</p> <p>The example below allocates memory for both a primitive type pointer, <code>intPointer</code>, and a pointer to a struct, <code>touchPoints</code>. It also binds the memory to the - Renderscript:</p> + RenderScript:</p> <pre> -private RenderScript myRenderscript; +private RenderScript myRenderScript; private ScriptC_example script; private Resources resources; public void init(RenderScript rs, Resources res) { - myRenderscript = rs; + myRenderScript = rs; resources = res; //allocate memory for the struct pointer, calling the constructor - ScriptField_Point touchPoints = new ScriptField_Point(myRenderscript, 2); + ScriptField_Point touchPoints = new ScriptField_Point(myRenderScript, 2); //Create an element manually and allocate memory for the int pointer - intPointer = Allocation.createSized(myRenderscript, Element.I32(myRenderscript), 2); + intPointer = Allocation.createSized(myRenderScript, Element.I32(myRenderScript), 2); - //create an instance of the Renderscript, pointing it to the bytecode resource - mScript = new ScriptC_example(myRenderscript, resources, R.raw.example); + //create an instance of the RenderScript, pointing it to the bytecode resource + mScript = new ScriptC_example(myRenderScript, resources, R.raw.example); - //bind the struct and int pointers to the Renderscript + //bind the struct and int pointers to the RenderScript mScript.bind_touchPoints(touchPoints); script.bind_intPointer(intPointer); @@ -618,29 +618,29 @@ public void init(RenderScript rs, Resources res) { </pre> <h3>Reading and writing to memory</h3> - <p>You can read and write to statically and dynamically allocated memory both at the Renderscript runtime + <p>You can read and write to statically and dynamically allocated memory both at the RenderScript runtime and Android framework layer.</p> <p>Statically allocated memory comes with a one-way communication restriction -at the Renderscript runtime level. When Renderscript code changes the value of a variable, it is not +at the RenderScript runtime level. When RenderScript code changes the value of a variable, it is not communicated back to the Android framework layer for efficiency purposes. The last value that is set from the Android framework is always returned during a call to a <code>get</code> method. However, when Android framework code modifies a variable, that change can be communicated to -the Renderscript runtime automatically or synchronized at a later time. If you need to send data -from the Renderscript runtime to the Android framework layer, you can use the +the RenderScript runtime automatically or synchronized at a later time. If you need to send data +from the RenderScript runtime to the Android framework layer, you can use the <a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function to overcome this limitation. </p> -<p>When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated +<p>When working with dynamically allocated memory, any changes at the RenderScript runtime layer are propagated back to the Android framework layer if you modified the memory allocation using its associated pointer. -Modifying an object at the Android framework layer immediately propagates that change back to the Renderscript +Modifying an object at the Android framework layer immediately propagates that change back to the RenderScript runtime layer.</p> <h4>Reading and writing to global variables</h4> <p>Reading and writing to global variables is a straightforward process. You can use the accessor methods - at the Android framework level or set them directly in the Renderscript code. Keep in mind that any - changes that you make in your Renderscript code are not propagated back to the Android framework layer.</p> + at the Android framework level or set them directly in the RenderScript code. Keep in mind that any + changes that you make in your RenderScript code are not propagated back to the Android framework layer.</p> <p>For example, given the following struct declared in a file named <code>rsfile.rs</code>:</p> <pre> @@ -659,8 +659,8 @@ point.x = 1; point.y = 1; </pre> -<p>You can assign values to the struct at the Android framework layer like this. These values are -propagated back to the Renderscript runtime level:</p> +<p>You can assign values to the struct at the Android framework layer like this. These values are +propagated back to the RenderScript runtime level:</p> <pre> ScriptC_rsfile mScript; @@ -672,7 +672,7 @@ i.y = 1; mScript.set_point(i); </pre> -<p>You can read the values in your Renderscript code like this:</p> +<p>You can read the values in your RenderScript code like this:</p> <pre> rsDebug("Printing out a Point", point.x, point.y); @@ -680,7 +680,7 @@ rsDebug("Printing out a Point", point.x, point.y); <p>You can read the values in the Android framework layer with the following code. Keep in mind that this code only returns a value if one was set at the Android framework level. You will get a null pointer -exception if you only set the value at the Renderscript runtime level:</p> +exception if you only set the value at the RenderScript runtime level:</p> <pre> Log.i("TAGNAME", "Printing out a Point: " + mScript.get_point().x + " " + mScript.get_point().y); @@ -689,9 +689,9 @@ System.out.println(point.get_x() + " " + point.get_y()); <h4>Reading and writing global pointers</h4> -<p>Assuming that memory has been allocated in the Android framework level and bound to the Renderscript runtime, +<p>Assuming that memory has been allocated in the Android framework level and bound to the RenderScript runtime, you can read and write memory from the Android framework level by using the <code>get</code> and <code>set</code> methods for that pointer. -In the Renderscript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated +In the RenderScript runtime layer, you can read and write to memory with pointers as normal and the changes are propagated back to the Android framework layer, unlike with statically allocated memory.</p> <p>For example, given the following pointer to a <code>struct</code> in a file named <code>rsfile.rs</code>:</p> @@ -726,5 +726,5 @@ ScriptField_Point p = new ScriptField_Point(mRS, 1); points.get_x(0); </pre> -<p>Once memory is already bound, you do not have to rebind the memory to the Renderscript +<p>Once memory is already bound, you do not have to rebind the memory to the RenderScript runtime every time you make a change to a value.</p> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index 5f466ce..607d16e 100644 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -1,4 +1,4 @@ -page.title=Renderscript Computation +page.title=RenderScript parent.title=Computation parent.link=index.html @@ -9,15 +9,8 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#overview">Renderscript System Overview</a></li> - <li><a href="#filterscript">Filterscript</a></li> - <li> - <a href="#creating-renderscript">Creating a Computation Renderscript</a> - <ol> - <li><a href="#creating-rs-file">Creating the Renderscript file</a></li> - <li><a href="#calling">Calling the Renderscript code</a></li> - </ol> - </li> + <li><a href="#writing-an-rs-kernel">Writing a RenderScript Kernel</a></li> + <li><a href="#using-rs-from-java">Using RenderScript from Java Code</a></li> </ol> <h2>Related Samples</h2> @@ -29,371 +22,204 @@ parent.link=index.html </div> </div> - <p>Renderscript offers a high performance computation API at the native -level that you write in C (C99 standard). Renderscript gives your apps the ability to run -operations with automatic parallelization across all available processor cores. -It also supports different types of processors such as the CPU, GPU or DSP. Renderscript -is useful for apps that do image processing, mathematical modeling, or any operations -that require lots of mathematical computation.</p> - -<p>In addition, you have access to all of these features without having to write code to -support different architectures or a different amount of processing cores. You also -do not need to recompile your application for different processor types, because Renderscript -code is compiled on the device at runtime.</p> - -<p class="note"><strong>Deprecation Notice</strong>: Earlier versions of Renderscript included - an experimental graphics engine component. This component -is now deprecated as of Android 4.1 (most of the APIs in <code>rs_graphics.rsh</code> -and the corresponding APIs in {@link android.renderscript}). -If you have apps that render graphics with Renderscript, we highly -recommend you convert your code to another Android graphics rendering option.</p> - - <h2 id="overview">Renderscript System Overview</h2> - <p>The Renderscript runtime operates at the native level and still needs to communicate -with the Android VM, so the way a Renderscript application is set up is different from a pure VM -application. An application that uses Renderscript is still a traditional Android application that -runs in the VM, but you write Renderscript code for the parts of your program that require -it. No matter what you use it for, Renderscript remains platform -independent, so you do not have to target multiple architectures (for example, -ARM v5, ARM v7, x86).</p> - -<p>The Renderscript system adopts a control and slave architecture where the low-level Renderscript runtime -code is controlled by the higher level Android system that runs in a virtual machine (VM). The -Android VM still retains all control of memory management and binds memory that it allocates to -the Renderscript runtime, so the Renderscript code can access it. The Android framework makes -asynchronous calls to Renderscript, and the calls are placed in a message queue and processed -as soon as possible. Figure 1 shows how the Renderscript system is structured.</p> - - <img id="figure1" src="{@docRoot}images/rs_overview.png" /> - <p class="img-caption"><strong>Figure 1.</strong> Renderscript system overview</p> - - <p>When using Renderscript, there are three layers of APIs that enable communication between the - Renderscript runtime and Android framework code:</p> - - <ul> - <li>The Renderscript runtime APIs allow you to do the computation - that is required by your application.</li> - - <li>The reflected layer APIs are a set of classes that are reflected from your Renderscript -runtime code. It is basically a wrapper around the Renderscript code that allows the Android -framework to interact with the Renderscript runtime. The Android build tools automatically generate the -classes for this layer during the build process. These classes eliminate the need to write JNI glue -code, like with the NDK.</li> - - <li>The Android framework layer calls the reflected layer to access the Renderscript - runtime.</li> - </ul> - -<p>Because of the way Renderscript is structured, the main advantages are:</p> - <ul> - <li>Portability: Renderscript is designed to run on many types of devices with different - processor (CPU, GPU, and DSP for instance) architectures. It supports all of these architectures without - having to target each device, because the code is compiled and cached on the device - at runtime.</li> - - <li>Performance: Renderscript provides a high performance computation API with seamless parallelization - across the amount of cores on the device.</li> - - <li>Usability: Renderscript simplifies development when possible, such as eliminating JNI glue code.</li> - </ul> - - <p>The main disadvantages are:</p> - - <ul> - <li>Development complexity: Renderscript introduces a new set of APIs that you have to learn.</li> - - <li>Debugging visibility: Renderscript can potentially execute (planned feature for later releases) - on processors other than the main CPU (such as the GPU), so if this occurs, debugging becomes more difficult. - </li> - </ul> - -<p>For a more detailed explanation of how all of these layers work together, see - <a href="{@docRoot}guide/topics/renderscript/advanced.html">Advanced Renderscript</a>.<p> - -<h2 id="filterscript">Filterscript</h2> - -<p>Introduced in Android 4.2 (API Level 17), Filterscript defines a subset of Renderscript -that focuses on image processing operations, such as those -that you would typically write with an OpenGL ES fragment shader. You still write your scripts -using the standard Renderscript runtime APIs, but within stricter -constraints that ensure wider compatibility and improved optimization across -CPUs, GPUs, and DSPs. At compile time, the precompiler evaluates Filterscript files and -applies a more stringent set of warnings and errors than -it does for standard Renderscript files. The following list describes the major constraints -of Filterscript when compared to Renderscript:</p> +<p>RenderScript is a framework for running computationally intensive tasks at high performance on +Android. RenderScript is primarily oriented for use with data-parallel computation, although serial +computationally intensive workloads can benefit as well. The RenderScript runtime will parallelize +work across all processors available on a device, such as multi-core CPUs, GPUs, or DSPs, allowing +you to focus on expressing algorithms rather than scheduling work or load balancing. RenderScript is +especially useful for applications performing image processing, computational photography, or +computer vision.</p> +<p>To begin with RenderScript, there are two main concepts you should understand:</p> <ul> -<li>Inputs and return values of root functions cannot contain pointers. The default root function -signature contains pointers, so you must use the <code>__attribute__((kernel))</code> attribute to declare a custom -root function when using Filterscript.</li> -<li>Built-in types cannot exceed 32-bits.</li> -<li>Filterscript must always use relaxed floating point precision by using the -<code>rs_fp_relaxed</code> pragma.</li> -<li>Filterscript files must end with an <code>.fs</code> extension, instead of an <code>.rs</code> extension.</li> -</ul> -<h2 id="creating-renderscript">Creating a Renderscript</h2> +<li>High-performance compute kernels are written in a C99-derived language.</li> -<p>Renderscript scales to the amount of -processing cores available on the device. This is enabled through a function named -<code>rsForEach()</code> (or the <code>forEach_root()</code> method at the Android framework level). -that automatically partitions work across available processing cores on the device.</p> +<li>A Java API is used for managing the lifetime of RenderScript resources and controlling kernel +execution.</li> +</ul> -<p>Implementing a Renderscript involves creating a <code>.rs</code> file that contains -your Renderscript code and calling it at the Android framework level with the -<code>forEach_root()</code> or at the Renderscript runtime level with the -<code>rsForEach()</code> function. The following diagram describes how a typical -Renderscript is set up:</p><img src="{@docRoot}images/rs_compute.png"> +<h2 id="writing-an-rs-kernel">Writing a RenderScript Kernel</h2> -<p class="img-caption"><strong>Figure 1.</strong> Renderscript overview</p> +<p>A RenderScript kernel typically resides in a <code>.rs</code> file in the +<code><project_root>/src/</code> directory; each <code>.rs</code> file is called a +script. Every script contains its own set of kernels, functions, and variables. A script can +contain:</p> -<p>The following sections describe how to create a simple Renderscript and use it in an -Android application. This example uses the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute Renderscript -sample</a> that is provided in the SDK as a guide (some code has been modified from its original -form for simplicity).</p> +<ul> +<li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of the +RenderScript kernel language used in this script. Currently, 1 is the only valid value.</li> + +<li>A pragma declaration (<code>#pragma rs java_package_name(com.example.app)</code>) that +declares the package name of the Java classes reflected from this script.</li> + +<li>Some number of invokable functions. An invokable function is a single-threaded RenderScript +function that you can call from your Java code with arbitrary arguments. These are often useful for +initial setup or serial computations within a larger processing pipeline.</li> + +<li>Some number of script globals. A script global is equivalent to a global variable in C. You can +access script globals from Java code, and these are often used for parameter passing to RenderScript +kernels.</li> + +<li>Some number of compute kernels. A kernel is a parallel function that executes across every +{@link android.renderscript.Element} within an {@link android.renderscript.Allocation}. + +<p>A simple kernel may look like the following:</p> + +<pre>uchar4 __attribute__((kernel)) invert(uchar4 in, uint32_t x, uint32_t y) { + uchar4 out = in; + out.r = 255 - in.r; + out.g = 255 - in.g; + out.b = 255 - in.b; + return out; +}</pre> + +<p>In most respects, this is identical to a standard C function. The first notable feature is the +<code>__attribute__((kernel))</code> applied to the function prototype. This denotes that the +function is a RenderScript kernel instead of an invokable function. The next feature is the +<code>in</code> argument and its type. In a RenderScript kernel, this is a special argument that is +automatically filled in based on the input {@link android.renderscript.Allocation} passed to the +kernel launch. By default, the kernel is run across an entire {@link +android.renderscript.Allocation}, with one execution of the kernel body per {@link +android.renderscript.Element} in the {@link android.renderscript.Allocation}. The third notable +feature is the return type of the kernel. The value returned from the kernel is automatically +written to the appropriate location in the output {@link android.renderscript.Allocation}. The +RenderScript runtime checks to ensure that the {@link android.renderscript.Element} types of the +input and output Allocations match the kernel's prototype; if they do not match, an exception is +thrown.</p> + +<p>A kernel may have an input {@link android.renderscript.Allocation}, an output {@link +android.renderscript.Allocation}, or both. A kernel may not have more than one input or one output +{@link android.renderscript.Allocation}. If more than one input or output is required, those objects +should be bound to <code>rs_allocation</code> script globals and accessed from a kernel or invokable +function via <code>rsGetElementAt_<em>type</em>()</code> or +<code>rsSetElementAt_<em>type</em>()</code>.</p> + +<p>A kernel may access the coordinates of the current execution using the <code>x</code>, +<code>y</code>, and <code>z</code> arguments. These arguments are optional, but the type of the +coordinate arguments must be <code>uint32_t</code>.</p></li> + +<li>An optional <code>init()</code> function. An <code>init()</code> function is a special type of +invokable function that is run when the script is first instantiated. This allows for some +computation to occur automatically at script creation.</li> + +<li>Some number of static script globals and functions. A static script global is equivalent to a +script global except that it cannot be set from Java code. A static function is a standard C +function that can be called from any kernel or invokable function in the script but is not exposed +to the Java API. If a script global or function does not need to be called from Java code, it is +highly recommended that those be declared <code>static</code>.</li> </ul> -<h3 id="creating-rs-file">Creating the Renderscript file</h3> +<h4>Setting floating point precision</h4> -<p>Your Renderscript code resides in <code>.rs</code> and <code>.rsh</code> files in the -<code><project_root>/src/</code> directory. This code contains the computation logic -and declares all necessary variables and pointers. -Every <code>.rs</code> file generally contains the following items:</p> +<p>You can control the required level of floating point precision in a script. This is useful if +full IEEE 754-2008 standard (used by default) is not required. The following pragmas can set a +different level of floating point precision:</p> <ul> - <li>A pragma declaration (<code>#pragma rs java_package_name(<em>package.name</em>)</code>) - that declares the package name of the <code>.java</code> reflection of this Renderscript.</li> - - <li>A pragma declaration (<code>#pragma version(1)</code>) that declares the version of - Renderscript that you are using (1 is the only value for now).</li> - - <li><p>A root function (or kernel) that is the main entry point to your Renderscript. - The default <code>root()</code> function must return - <code>void</code> and accept the following arguments:</p> - - <ul> - <li>Pointers to memory allocations that are used for the input and output of the - Renderscript. Both of these pointers are required for Android 3.2 (API level 13) platform - versions or older. Android 4.0 (API level 14) and later requires one or both of these - allocations.</li> - </ul> - - <p>The following arguments are optional, but both must be supplied if you choose to use - them:</p> - - <ul> - <li>A pointer for user-defined data that the Renderscript might need to carry out - computations in addition to the necessary allocations. This can be a pointer to a simple - primitive or a more complex struct.</li> - - <li>The size of the user-defined data.</li> - </ul> - - <p>Starting in Android 4.1 (API Level 16), you can choose to define your own root function arguments - without adhering to the default root function signature described previously. In addition, - you can declare multiple root functions in the same Renderscript. To do this, use the <code>__attribute__((kernel))</code> - attribute to define a custom root function. For example, here's a root function - that returns a <code>uchar4</code> and accepts two <code>uint32_t</code> types: </p> - - <pre> - uchar4 __attribute__((kernel)) root(uint32_t x, uint32_t y) { - ... - } - </pre> - </li> - - <li>An optional <code>init()</code> function. This allows you to do any initialization - before the root function runs, such as initializing variables. This - function runs once and is called automatically when the Renderscript starts, before anything - else in your Renderscript.</li> - - <li>Any variables, pointers, and structures that you wish to use in your Renderscript code (can - be declared in <code>.rsh</code> files if desired)</li> -</ul> -<p>The following code shows how the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/src/com/example/android/rs/hellocompute/mono.html"> -mono.rs</a> file is implemented:</p> -<pre> -#pragma version(1) -#pragma rs java_package_name(com.example.android.rs.hellocompute) - -//multipliers to convert a RGB colors to black and white -const static float3 gMonoMult = {0.299f, 0.587f, 0.114f}; - -void root(const uchar4 *v_in, uchar4 *v_out) { - //unpack a color to a float4 - float4 f4 = rsUnpackColor8888(*v_in); - //take the dot product of the color and the multiplier - float3 mono = dot(f4.rgb, gMonoMult); - //repack the float to a color - *v_out = rsPackColorTo8888(mono); -} -</pre> +<li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that require + floating point precision as outlined by the IEEE 754-2008 standard. -<h4>Setting floating point precision</h4> -<p>You can define the floating point precision required by your compute algorithms. This is useful if you - require less precision than the IEEE 754-2008 standard (used by default). You can define -the floating-point precision level of your script with the following pragmas:</p> - -<ul> - <li><code>#pragma rs_fp_full</code> (default if nothing is specified): For apps that - require floating point precision as outlined by the IEEE 754-2008 standard. </li> - <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require - strict IEEE 754-2008 compliance and can tolerate less precision. This mode enables - flush-to-zero for denorms and round-towards-zero. + + <li><code>#pragma rs_fp_relaxed</code> - For apps that don’t require strict IEEE 754-2008 + compliance and can tolerate less precision. This mode enables flush-to-zero for denorms and + round-towards-zero. + </li> - <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision requirements. This mode enables - everything in <code>rs_fp_relaxed</code> along with the following: + + <li><code>#pragma rs_fp_imprecise</code> - For apps that don’t have stringent precision + requirements. This mode enables everything in <code>rs_fp_relaxed</code> along with the + following: + <ul> + <li>Operations resulting in -0.0 can return +0.0 instead.</li> <li>Operations on INF and NAN are undefined.</li> </ul> </li> </ul> -<h4>Script intrinsics</h4> -<p>Renderscript adds support for a set of script intrinsics, which are pre-implemented -filtering primitives that reduce the amount of -code that you need to write. They also are implemented to ensure that your app gets the -maximum performance gain possible.</p> +<p>Most applications can use <code>rs_fp_relaxed</code> without any side effects. This may be very +beneficial on some architectures due to additional optimizations only available with relaxed +precision (such as SIMD CPU instructions).</p> -<p> -Intrinsics are available for the following: -<ul> - <li>{@link android.renderscript.ScriptIntrinsicBlend Blends}</li> - <li>{@link android.renderscript.ScriptIntrinsicBlur Blur}</li> - <li>{@link android.renderscript.ScriptIntrinsicColorMatrix Color matrix}</li> - <li>{@link android.renderscript.ScriptIntrinsicConvolve3x3 3x3 convolve}</li> - <li>{@link android.renderscript.ScriptIntrinsicConvolve5x5 5x5 convolve}</li> - <li>{@link android.renderscript.ScriptIntrinsicLUT Per-channel lookup table}</li> - <li>{@link android.renderscript.ScriptIntrinsicYuvToRGB Converting an Android YUV buffer to RGB}</li> -</ul> +<h2 id="using-rs-from-java">Using RenderScript from Java Code</h2> -<h3 id="calling">Calling the Renderscript code</h3> +<p>Using RenderScript from Java code relies on the {@link android.renderscript} APIs. Most +applications follow the same basic usage patterns:</p> -<p>You can call the Renderscript from your Android framework code by -creating a Renderscript object by instantiating the (<code>ScriptC_<em>script_name</em></code>) -class. This class contains a method, <code>forEach_root()</code>, that lets you invoke -<code>rsForEach</code>. You give it the same parameters that you would if you were invoking it -at the Renderscript runtime level. This technique allows your Android application to offload -intensive mathematical calculations to Renderscript. See the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample to see -how a simple Android application can utilize Renderscript.</p> +<ol> -<p>To call Renderscript at the Android framework level:</p> +<li><strong>Initialize a RenderScript context.</strong> The {@link +android.renderscript.RenderScript} context, created with {@link +android.renderscript.RenderScript#create}, ensures that RenderScript can be used and provides an +object to control the lifetime of all subsequent RenderScript objects. You should consider context +creation to be a potentially long-running operation, since it may create resources on different +pieces of hardware; it should not be in an application's critical path if at all +possible. Typically, an application will have only a single RenderScript context at a time.</li> + +<li><strong>Create at least one {@link android.renderscript.Allocation} to be passed to a +script.</strong> An {@link android.renderscript.Allocation} is a RenderScript object that provides +storage for a fixed amount of data. Kernels in scripts take {@link android.renderscript.Allocation} +objects as their input and output, and {@link android.renderscript.Allocation} objects can be +accessed in kernels using <code>rsGetElementAt_<em>type</em>()</code> and +<code>rsSetElementAt_<em>type</em>()</code> when bound as script globals. {@link +android.renderscript.Allocation} objects allow arrays to be passed from Java code to RenderScript +code and vice-versa. {@link android.renderscript.Allocation} objects are typically created using +{@link android.renderscript.Allocation#createTyped} or {@link +android.renderscript.Allocation#createFromBitmap}.</li> + +<li><strong>Create whatever scripts are necessary.</strong> There are two types of scripts available +to you when using RenderScript: -<ol> - <li>Allocate memory that is needed by the Renderscript in your Android framework code. - You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level - 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only - one or both {@link android.renderscript.Allocation}s.</li> - - <li>Create an instance of the <code>ScriptC_<em>script_name</em></code> class.</li> - - <li>Call <code>forEach_root()</code>, passing in the allocations, the - Renderscript, and any optional user-defined data. The output allocation will contain the output - of the Renderscript.</li> -</ol> - -<p>The following example, taken from the <a href= -"{@docRoot}resources/samples/RenderScript/HelloCompute/index.html">HelloCompute</a> sample, processes -a bitmap and outputs a black and white version of it. The -<code>createScript()</code> method carries out the steps described previously. This method calls the -Renderscript, <code>mono.rs</code>, passing in memory allocations that store the bitmap to be processed -as well as the eventual output bitmap. It then displays the processed bitmap onto the screen:</p> -<pre> -package com.example.android.rs.hellocompute; - -import android.app.Activity; -import android.os.Bundle; -import android.graphics.BitmapFactory; -import android.graphics.Bitmap; -import android.renderscript.RenderScript; -import android.renderscript.Allocation; -import android.widget.ImageView; - -public class HelloCompute extends Activity { - private Bitmap mBitmapIn; - private Bitmap mBitmapOut; - - private RenderScript mRS; - private Allocation mInAllocation; - private Allocation mOutAllocation; - private ScriptC_mono mScript; - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.main); - - mBitmapIn = loadBitmap(R.drawable.data); - mBitmapOut = Bitmap.createBitmap(mBitmapIn.getWidth(), mBitmapIn.getHeight(), - mBitmapIn.getConfig()); - - ImageView in = (ImageView) findViewById(R.id.displayin); - in.setImageBitmap(mBitmapIn); - - ImageView out = (ImageView) findViewById(R.id.displayout); - out.setImageBitmap(mBitmapOut); - - createScript(); - } - private void createScript() { - mRS = RenderScript.create(this); - mInAllocation = Allocation.createFromBitmap(mRS, mBitmapIn, - Allocation.MipmapControl.MIPMAP_NONE, - Allocation.USAGE_SCRIPT); - mOutAllocation = Allocation.createTyped(mRS, mInAllocation.getType()); - mScript = new ScriptC_mono(mRS, getResources(), R.raw.mono); - mScript.forEach_root(mInAllocation, mOutAllocation); - mOutAllocation.copyTo(mBitmapOut); - } - - private Bitmap loadBitmap(int resource) { - final BitmapFactory.Options options = new BitmapFactory.Options(); - options.inPreferredConfig = Bitmap.Config.ARGB_8888; - return BitmapFactory.decodeResource(getResources(), resource, options); - } -} -</pre> - -<p>To call Renderscript from another Renderscript file:</p> -<ol> - <li>Allocate memory that is needed by the Renderscript in your Android framework code. - You need an input and output {@link android.renderscript.Allocation} for Android 3.2 (API level - 13) platform versions and older. The Android 4.0 (API level 14) platform version requires only - one or both {@link android.renderscript.Allocation}s.</li> - - <li>Call <code>rsForEach()</code>, passing in the allocations and any optional user-defined data. - The output allocation will contain the output of the Renderscript.</li> -</ol> - -<pre> -rs_script script; -rs_allocation in_allocation; -rs_allocation out_allocation; -UserData_t data; -... -rsForEach(script, in_allocation, out_allocation, &data, sizeof(data)); -</pre> -</p> -<p>In this example, assume that the script and memory allocations have already been -allocated and bound at the Android framework level and that <code>UserData_t</code> is a struct -declared previously. Passing a pointer to a struct and the size of the struct to <code>rsForEach</code> -is optional, but useful if your Renderscript requires additional information other than -the necessary memory allocations.</p> - - -<h4>Script groups</h4> - -<p>You can group Renderscript scripts together and execute them all with a single call as though -they were part of a single script. This allows Renderscript to optimize execution of the scripts -in ways that it could not do if the scripts were executed individually.</p> - -<p>To build a script groupm, use the {@link android.renderscript.ScriptGroup.Builder} class to create a {@link android.renderscript.ScriptGroup} -defining the operations. At execution time, Renderscript optimizes the run order and the connections between these -operations for best performance. - -<p class="note"><strong>Important:</strong> The script group must be a direct acyclic graph for this feature to work.</p> +<ul> + +<li><strong>ScriptC</strong>: These are the user-defined scripts as described in <a +href="#writing-an-rs-kernel">Writing a RenderScript Kernel</a> above. Every script has a Java class +reflected by the RenderScript compiler in order to make it easy to access the script from Java code; +this class will have the name <code>ScriptC_<em>filename</em></code>. For example, if the kernel +above was located in <code>invert.rs</code> and a RenderScript context was already located in +<code>mRS</code>, the Java code to instantiate the script would be: + +<pre>ScriptC_invert invert = new ScriptC_invert(mRenderScript);</pre></li> + +<li><strong>ScriptIntrinsic</strong>: These are built-in RenderScript kernels for common operations, +such as Gaussian blur, convolution, and image blending. For more information, see the subclasses of +{@link android.renderscript.ScriptIntrinsic}.</li> + +</ul></li> + +<li><strong>Populate Allocations with data.</strong> Except for Allocations created with {@link +android.renderscript#createFromBitmap}, an Allocation will be populated with empty data when it is +first created. To populate an Allocation, use one of the <code>copy</code> methods in {@link +android.renderscript.Allocation}.</li> + +<li><strong>Set any necessary script globals.</strong> Globals may be set using methods in the same +<code>ScriptC_<em>filename</em></code> class with methods named +<code>set_<em>globalname</em></code>. For example, in order to set an <code>int</code> named +<code>elements</code>, use the Java method <code>set_elements(int)</code>. RenderScript objects can +also be set in kernels; for example, the <code>rs_allocation</code> variable named +<code>lookup</code> can be set with the method <code>set_lookup(Allocation)</code>.</li> + +<li><strong>Launch the appropriate kernels.</strong> Methods to launch a given kernel will be +reflected in the same <code>ScriptC_<em>filename</em></code> class with methods named +<code>forEach_<em>kernelname</em>()</code>. These launches are asynchronous, and launches will be +serialized in the order in which they are launched. Depending on the arguments to the kernel, the +method will take either one or two Allocations. By default, a kernel will execute over the entire +input or output Allocation; to execute over a subset of that Allocation, pass an appropriate {@link +android.renderscript.Script.LaunchOptions} as the last argument to the <code>forEach</code> method. + +<p>Invoked functions can be launched using the <code>invoke_<em>functionname</em></code> methods +reflected in the same <code>ScriptC_<em>filename</em></code> class.</p></li> + +<li><strong>Copy data out of {@link android.renderscript.Allocation} objects.</strong> In order to +access data from an {@link android.renderscript.Allocation} from Java code, that data must be copied +back to Java buffers using one of the <code>copy</code> methods in {@link +android.renderscript.Allocation}. These functions will synchronize with asynchronous kernel and +function launches as necessary.</li> + +<li><strong>Tear down the RenderScript context.</strong> The RenderScript context can be destroyed +with {@link android.renderscript.RenderScript#destroy} or by allowing the RenderScript context +object to be garbage collected. This will cause any further use of any object belonging to that +context to throw an exception.</li> </ol>
\ No newline at end of file diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd index b5c53ff..d23ba69 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/renderscript/index.jd @@ -1,6 +1,6 @@ page.title=Computation page.landing=true -page.landing.intro=Renderscript provides a platform-independent computation engine that operates at the native level. Use it to accelerate your apps that require extensive computational horsepower. +page.landing.intro=RenderScript provides a platform-independent computation engine that operates at the native level. Use it to accelerate your apps that require extensive computational horsepower. page.landing.image= @jd:body @@ -12,16 +12,16 @@ page.landing.image= <a href="http://android-developers.blogspot.com/2013/01/evolution-of-renderscript-performance.html"> - <h4>Evolution of Renderscript Performance</h4> - <p>It’s been a year since the last blog post on Renderscript, and with the release + <h4>Evolution of RenderScript Performance</h4> + <p>It’s been a year since the last blog post on RenderScript, and with the release of Android 4.2, it’s a good time to talk about the performance work that we’ve done since then. One of the major goals of this past year was to improve the performance - of common image-processing operations with Renderscript.</p> </a> + of common image-processing operations with RenderScript.</p> </a> <a href="http://android-developers.blogspot.com/2012/01/levels-in-renderscript.html"> - <h4>Levels in Renderscript</h4> - <p>For ICS, Renderscript (RS) has been updated with several new features to simplify + <h4>Levels in RenderScript</h4> + <p>For ICS, RenderScript (RS) has been updated with several new features to simplify adding compute acceleration to your application. RS is interesting for compute acceleration when you have large buffers of data on which you need to do significant processing. In this example we will look at applying a levels/saturation operation @@ -30,11 +30,11 @@ href="http://android-developers.blogspot.com/2012/01/levels-in-renderscript.html <a href="http://android-developers.blogspot.com/2011/03/renderscript.html"> - <h4>Renderscript Part 2</h4> - <p>In Introducing Renderscript I gave a brief overview of this technology. - In this post I’ll look at "compute" in more detail. In Renderscript we use + <h4>RenderScript Part 2</h4> + <p>In Introducing RenderScript I gave a brief overview of this technology. + In this post I’ll look at "compute" in more detail. In RenderScript we use "compute" to mean offloading of data processing from Dalvik code to - Renderscript code which may run on the same or different processor(s).</p> + RenderScript code which may run on the same or different processor(s).</p> </a> </div> diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index a34ed6c..dee28fe 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -174,6 +174,7 @@ In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" | "fill_vertical" | "center_horizontal" | "fill_horizontal" | "center" | "fill" | "clip_vertical" | "clip_horizontal"] + android:mipMap=["true" | "false"] android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] /> </pre> </dd> @@ -245,6 +246,12 @@ the right edge, a right gravity clips the left edge, and neither clips both edge </td></tr> </table> </dd> + + <dt><code>android:mipMap</code></dt> + <dd><em>Boolean</em>. Enables or disables the mipmap hint. See {@link + android.graphics.Bitmap#setHasMipMap setHasMipMap()} for more information. + Default value is false.</dd> + <dt><code>android:tileMode</code></dt> <dd><em>Keyword</em>. Defines the tile mode. When the tile mode is enabled, the bitmap is repeated. Gravity is ignored when the tile mode is enabled. diff --git a/docs/html/images/mediadrm_decryption_sequence.png b/docs/html/images/mediadrm_decryption_sequence.png Binary files differnew file mode 100644 index 0000000..2bd95ea --- /dev/null +++ b/docs/html/images/mediadrm_decryption_sequence.png diff --git a/docs/html/images/mediadrm_overview.png b/docs/html/images/mediadrm_overview.png Binary files differnew file mode 100644 index 0000000..dd66bce --- /dev/null +++ b/docs/html/images/mediadrm_overview.png diff --git a/docs/html/training/location/receive-location-updates.jd b/docs/html/training/location/receive-location-updates.jd index c33f075..e6e8c51 100644 --- a/docs/html/training/location/receive-location-updates.jd +++ b/docs/html/training/location/receive-location-updates.jd @@ -417,7 +417,7 @@ public class MainActivity extends FragmentActivity implements public static final int UPDATE_INTERVAL_IN_SECONDS = 5; // Update frequency in milliseconds private static final long UPDATE_INTERVAL = - MILLISECONDS_PER_SECOND * UPDATE_INTERVAL_IN SECONDS; + MILLISECONDS_PER_SECOND * UPDATE_INTERVAL_IN_SECONDS; // The fastest update frequency, in seconds private static final int FASTEST_INTERVAL_IN_SECONDS = 1; // A fast frequency ceiling in milliseconds @@ -425,7 +425,7 @@ public class MainActivity extends FragmentActivity implements MILLISECONDS_PER_SECOND * FASTEST_INTERVAL_IN_SECONDS; ... // Define an object that holds accuracy and frequency parameters - LocationResult mLocationRequest; + LocationRequest mLocationRequest; ... @Override protected void onCreate(Bundle savedInstanceState) { @@ -458,9 +458,11 @@ public class MainActivity extends FragmentActivity implements the request by calling <code><a href="{@docRoot}reference/com/google/android/gms/location/LocationClient.html#requestLocationUpdates(com.google.android.gms.location.LocationRequest, com.google.android.gms.location.LocationListener)">requestLocationUpdates()</a></code>. Since your client must be connected for your app to receive updates, you should - connect the client and make the request in + connect the client in {@link android.support.v4.app.FragmentActivity#onStart onStart()}. This ensures that you always - have a valid, connected client while your app is visible. + have a valid, connected client while your app is visible. Since you need a connection before you + can request updates, make the update request in +<code><a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesClient.ConnectionCallbacks.html#onConnected(android.os.Bundle)">ConnectionCallbacks.onConnected()</a></code> </p> <p> Remember that the user may want to turn off location updates for various reasons. You should @@ -536,6 +538,21 @@ public class MainActivity extends FragmentActivity implements } } ... + /* + * Called by Location Services when the request to connect the + * client finishes successfully. At this point, you can + * request the current location or start periodic updates + */ + @Override + public void onConnected(Bundle dataBundle) { + // Display the connection status + Toast.makeText(this, "Connected", Toast.LENGTH_SHORT).show(); + // If already requested, start periodic updates + if (mUpdatesRequested) { + mLocationClient.requestLocationUpdates(mLocationRequest, this); + } + } + ... } </pre> <p> |
