【翻译】(80)Renderscript之计算

【翻译】(80)Renderscript之计算

 

see

http://developer.android.com/guide/topics/renderscript/compute.html

 

原文见

http://developer.android.com/guide/topics/renderscript/compute.html

 

-------------------------------

 

Compute

 

Renderscript之计算

 

-------------------------------

 

In this document

 

本文目录

 

* Creating a Compute Renderscript 创建一个计算Renderscript

* Creating the Renderscript file 创建Renderscript文件

* Calling the Renderscript code 调用Renderscript代码

 

Related Samples

 

相关示例

 

* Hello Compute 你好计算

* Balls 球

 

-------------------------------

 

Renderscript exposes a set of compute APIs that you can use to do intensive computational operations. You can use the compute APIs in the context of a graphics Renderscript such as calculating the positions of many objects in a scene. You can also create standalone compute Renderscripts such as one that does image processing for a photo editor application.

 

Renderscript暴露一组计算API，你可以使用它们来执行密集的计算型操作。你可以在一个图形Renderscript的上下文中使用计算API，诸如计算场景中许多对象的位置。你还可以创建独立的计算Renderscript，诸如用于相片编辑器应用程序的一个执行图片处理的Renderscript。

 

Compute Renderscripts scale to the amount of processing cores available on the device. This is enabled through a function named rsForEach() (or the forEach_root() method at the Android framework level). that automatically partitions work across available processing cores on the device. For now, compute Renderscripts can only take advantage of CPU cores, but in the future, they can potentially run on other types of processors such as GPUs and DSPs.

 

计算Renderscript伸缩至设备上可用的处理（注：这里的processing应该是指处理器，下同）核心个数。这通过一个名为rsForEach()的函数被使能（或者在Android框架层上的forEach_root()方法）。它自动地划分工作，跨越设备上的可用处理核心。目前，计算Renderscript只可以利用CPU核心，但在未来，它们可以隐式地运行在其它类型的处理器上，诸如GPU和DSP。

 

-------------------------------

 

Creating a Compute Renderscript

 

创建一个计算Renderscript

 

Implementing a compute Renderscript creating a .rs file that contains your Renderscript code and calling it at the Android framework level with the forEach_root() or at the Renderscript runtime level with the rsForEach() function. The following diagram describes how a typical compute Renderscript is set up:

 

实现一个计算Renderscript，通过创建一个包含你的Renderscript代码的.rs文件，并在Android框架层上用forEach_root()或在Renderscript运行时层上用rsForEach()函数调用它。以下图表描述一个典型的计算Renderscript是如何被配置的：

 

-------------------------------

 

（图略：

1. Android框架（左图）

 

（“Android框架”包含）活动

 

（“活动”包含）Renderscript上下文

 

--o

 

（“活动”包含）Renderscript对象

 

--o（连接至“计算Renderscript”）

 

2. Renderscript运行时（右图）

（“Renderscript运行时”包含）计算Renderscript（.rs）

 

-->

 

（“Renderscript运行时”包含）Renderscript计算引擎

）

 

Figure 1. Compute Renderscript overview

 

图1. 计算Renderscript概览

 

-------------------------------

 

The following sections describe how to create a simple compute Renderscript and use it in an Android application. This example uses the HelloCompute Renderscript sample that is provided in the SDK as a guide (some code has been modified from its original form for simplicity).

 

以下章节描述如何创建一个简单的计算Renderscript并在一个Android应用程序中使用它。这个示例使用SDK中的HelloCompute的Renderscript示例作为一个指引（简单起见，一些代码已经被修改自它原来的形式）。

 

Creating the Renderscript file

 

创建Renderscript文件

 

Your Renderscript code resides in .rs and .rsh files in the <project_root>/src/ directory. This code contains the compute logic and declares all necessary variables and pointers. Every compute .rs file generally contains the following items:

 

你的Renderscript代码寄居在<project_root>/src/目录下的.rs和.rsh文件中。这个代码包含计算逻辑并声明所有必需的变量和指针。每个计算.rs文件通常包含以下条目：

 

* A pragma declaration (#pragma rs java_package_name(package.name)) that declares the package name of the .java reflection of this Renderscript.

 

* 一个pragma声明（#pragma rs java_package_name(package.name)），它声明这个Renderscript的.java反射的包名。

 

* A pragma declaration (#pragma version(1)) that declares the version of Renderscript that you are using (1 is the only value for now).

 

* 一个pragma声明（#pragma version(1)），它声明你正在使用的Renderscript的版本（目前1是唯一的值）。

 

* A root() function that is the main worker function. The root function is called by the rsForEach function, which allows the Renderscript code to be called and executed on multiple cores if they are available. The root() function must return void and accept the following arguments:

 

* 一个root()函数，它是主工作者函数。root函数被rsForEach函数调用，它允许Renderscript代码被调用和执行在多核上，如果它们是可用的。root()函数必须返回void和接受以下参数：

 

* Pointers to memory allocations that are used for the input and output of the compute 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.

 

* 指向内存分配的指针，它被用于计算Renderscript的输入和输出。这两种指针都是必需的，对于Android 3.2（API级别13）平台版本或更旧来说。Android 4.0（API级别14）和更晚需要这些分配中的一个或两个。

 

The following arguments are optional, but both must be supplied if you choose to use them:

 

以下参数是可选的，但必须同时提供两者如果你选择使用它们：

 

* 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.

 

* 一个用户定义数据的指针，Renderscript可能需要它来履行计算，除了必需的分配外。这可能是一个指向简单原始（注：原始类型）值或一个更复杂的结构体的指针。

 

* The size of the user-defined data.

 

* 用户定义数据的大小。

 

* An optional init() 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.

 

* 一个可选的init()函数。它允许你在root()函数运行前执行任意初始化，诸如初始化变量。这个函数运行一次，并且在Renderscript开始时自动地被调用，在你的Renderscript中其它任意事情发生之前。

 

* Any variables, pointers, and structures that you wish to use in your Renderscript code (can be declared in .rsh files if desired)

 

* 你希望在你的Renderscript代码中使用的任意变量、指针和结构体（可以被声明在.rsh文件中，如果这是你所期望的）

 

The following code shows how the mono.rs file is implemented:

 

以下代码展示mono.rs文件是如何被实现的：

 

-------------------------------

 

#pragma version(1)

#pragma rs java_package_name(com.example.android.rs.hellocompute)

 

//multipliers to convert a RGB colors to black and white

//转换一个RGB颜色为黑色和白色的乘数

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

  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);

}

 

-------------------------------

 

Calling the Renderscript code

 

调用Renderscript代码

 

You can do Renderscript to Renderscript calls with rsForEach in situations such as when a graphics Renderscript needs to do a lot of computational operations. The Renderscript Balls sample shows how this is setup. The balls.rs graphics Renderscript calls the balls_physics.rs compute Renderscript to calculate the location of the balls that are rendered to the screen.

 

你可以使用rsForEach执行Renderscript到Renderscript调用，在这些情况下诸如当一个图形Renderscript需要做许多计算型的操作。Renderscript球示例展示它是如何被配置的。balls.rs图形Renderscript调用balls_physics.rs计算Renderscript以计算被渲染到屏幕的球的位置。

 

Another way to use a compute Renderscript is to call it from your Android framework code by creating a Renderscript object by instantiating the (ScriptC_script_name) class. This class contains a method, forEach_root(), that lets you invoke rsForEach. 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 HelloCompute sample to see how a simple Android application can utilize a compute Renderscript.

 

使用一个计算Renderscript的另一种方式是通过由实例化(ScriptC_script_name)类创建的一个Renderscript对象，从你的Android框架代码中调用它。这个类包含一个方法，forEach_root()，它让你调用rsForEach。你给予它和你会在Renderscript运行时层上调用它的情况下给予的相同参数。这项技术允许你的Android应用程序把密集的数学计算托付（注：卸货）给Renderscript。参见HelloCompute以知道一个简单的应用程序可以如何利用一个计算Renderscript。

 

To call a compute Renderscript at the Android framework level:

 

为了在Android框架层上调用一个计算Renderscript：

 

1. Allocate memory that is needed by the compute Renderscript in your Android framework code. You need an input and output 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 Allocations.

 

1. 在你的Android框架代码中计算Renderscript需要的分配内存。对于Android 3.2（API级别13）平台和更旧，你需要一个输入和输出Allocation。Android 4.0（API级别14）平台版本只需要一个或两个Allocation。

 

2. Create an instance of the ScriptC_script_name class.

 

2. 创建ScriptC_script_name类的一个实例。

 

3. Call forEach_root(), passing in the allocations, the Renderscript, and any optional user-defined data. The output allocation will contain the output of the compute Renderscript.

 

3. 调用forEach_root()，传递进分配，Renderscript，以及任意可选的用户定义数据。输出分配将包含计算Renderscript的输出。

 

In the following example, taken from the HelloCompute sample, processes a bitmap and outputs a black and white version of it. The createScript() method carries out the steps described previously. This method the compute Renderscript, mono.rs, 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:

 

在以下取自HelloCompute示例的例子中，处理一个位图并输出它的一个黑色和白色版本。createScript()方法履行前面描述的步骤。这个方法，计算Renderscript mono.rs传递进要被处理的存储位图的内存分配以及最终的输出位图。然后它显示被处理的位图到屏幕上：

 

-------------------------------

 

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);

  }

}

 

-------------------------------

 

To call a compute Renderscript from another Renderscript file:

 

为了从另一个Renderscript文件中调用一个计算Renderscript：

 

1. Allocate memory that is needed by the compute Renderscript in your Android framework code. You need an input and output 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 Allocations.

 

1. 在你的Android框架代码中计算Renderscript所需的分配内存。对于Android 3.2（API级别13）平台版本和更旧，你需要一个输入和输出分配。Android 4.0（API级别14）平台版本只需要一个或两个Allocation。

 

2. Call rsForEach(), passing in the allocations and any optional user-defined data. The output allocation will contain the output of the compute Renderscript.

 

2. 调用rsForEach()，传递进分配和任意可选的用户定义数据。输出分配将包含计算Renderscript的输出。

 

The following example, taken from the Renderscript Balls sample, demonstrates how to do make a script to script call:

 

以下示例，取自Renderscript的球示例，演示如何制造一个脚本到脚本的调用：

 

-------------------------------

 

rs_script script;

rs_allocation in_allocation;

rs_allocation out_allocation;

UserData_t data;

...

rsForEach(script, in_allocation, out_allocation, &data, sizeof(data));

 

-------------------------------

 

In this example, assume that the script and memory allocations have already been allocated and bound at the Android framework level and that UserData_t is a struct declared previously. Passing a pointer to a struct and the size of the struct to rsForEach is optional, but useful if your compute Renderscript requires additional information other than the necessary memory allocations.

 

在这个示例中，假设脚本和内存分配已经被分配和在Android框架层上绑定，而UserData_t是之前声明的一个struct。传递一个指向一个struct的指针和struct的大小给rsForEach是可选的，但它是有用的如果你的计算Renderscript需要额外的信息而非必需的内存分配。

 

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

 

除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。

 

Android 4.0 r1 - 02 Apr 2012 19:36

 

-------------------------------

 

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

 

此页部分内容，是基于Android开源项目所创建和共享的工作，并且根据知识共享2.5署名许可证描述的条款来使用的修改版。

 

（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：

* ソフトウェア技術ドキュメントを勝手に翻訳

http://www.techdoctranslator.com/android

* Ley's Blog

http://leybreeze.com/blog/

* 农民伯伯

http://www.cnblogs.com/over140/

* Android中文翻译组

http://androidbox.sinaapp.com/

）