From 11518acc8c416023d8c2192b441a1767205676d9 Mon Sep 17 00:00:00 2001 From: Robert Ly Date: Wed, 9 Feb 2011 13:57:06 -0800 Subject: clean up and add javadocs Change-Id: I7f628106247de887cd91c4a4b4b55d3ebfa700c8 --- graphics/java/android/renderscript/Allocation.java | 44 ++++++++--- graphics/java/android/renderscript/Byte2.java | 2 +- graphics/java/android/renderscript/Byte3.java | 2 +- graphics/java/android/renderscript/Byte4.java | 2 +- graphics/java/android/renderscript/Element.java | 33 +++++---- .../java/android/renderscript/FieldPacker.java | 4 +- graphics/java/android/renderscript/FileA3D.java | 8 +- graphics/java/android/renderscript/Float2.java | 2 +- graphics/java/android/renderscript/Float3.java | 2 +- graphics/java/android/renderscript/Float4.java | 2 +- graphics/java/android/renderscript/Font.java | 15 +++- graphics/java/android/renderscript/Int2.java | 2 +- graphics/java/android/renderscript/Int3.java | 2 +- graphics/java/android/renderscript/Int4.java | 2 +- graphics/java/android/renderscript/Long2.java | 2 +- graphics/java/android/renderscript/Long3.java | 2 +- graphics/java/android/renderscript/Long4.java | 2 +- graphics/java/android/renderscript/Matrix2f.java | 2 +- graphics/java/android/renderscript/Matrix3f.java | 2 +- graphics/java/android/renderscript/Matrix4f.java | 2 +- graphics/java/android/renderscript/Mesh.java | 29 ++++---- .../java/android/renderscript/ProgramFragment.java | 16 +++- .../renderscript/ProgramFragmentFixedFunction.java | 10 +-- .../java/android/renderscript/ProgramRaster.java | 3 +- .../java/android/renderscript/ProgramStore.java | 19 ++--- .../java/android/renderscript/ProgramVertex.java | 21 ++++++ .../java/android/renderscript/RSSurfaceView.java | 2 +- graphics/java/android/renderscript/Sampler.java | 4 +- graphics/java/android/renderscript/Short2.java | 2 +- graphics/java/android/renderscript/Short3.java | 2 +- graphics/java/android/renderscript/Short4.java | 2 +- graphics/java/android/renderscript/Type.java | 12 +-- graphics/java/android/renderscript/package.html | 85 ++++++++++++++++++++++ 33 files changed, 246 insertions(+), 95 deletions(-) create mode 100644 graphics/java/android/renderscript/package.html (limited to 'graphics/java') diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java index 3dcfe88..4b8c58e 100644 --- a/graphics/java/android/renderscript/Allocation.java +++ b/graphics/java/android/renderscript/Allocation.java @@ -26,19 +26,41 @@ import android.util.Log; import android.util.TypedValue; /** - * Memory allocation class for renderscript. An allocation combines a Type with - * memory to provide storage for user data and objects. + *

+ * Memory allocation class for renderscript. An allocation combines a + * {@link android.renderscript.Type} with the memory to provide storage for user data and objects. + * This implies that all memory in Renderscript is typed. + *

* - * Allocations may exist in one or more memory spaces. Currently those are - * Script: accessable by RS scripts. - * Graphics Texture: accessable as a graphics texture. - * Graphics Vertex: accessable as graphical vertex data. - * Graphics Constants: Accessable as constants in user shaders + *

Allocations are the primary way data moves into and out of scripts. Memory is user + * synchronized and it's possible for allocations to exist in multiple memory spaces + * concurrently. Currently those spaces are:

+ * + *

+ *

+ * For example, when creating a allocation for a texture, the user can + * specify its memory spaces as both script and textures. This means that it can both + * be used as script binding and as a GPU texture for rendering. To maintain + * synchronization if a script modifies an allocation used by other targets it must + * call a synchronizing function to push the updates to the memory, otherwise the results + * are undefined. + *

+ *

By default, Android system side updates are always applied to the script accessable + * memory. If this is not present, they are then applied to the various HW + * memory types. A {@link android.renderscript.Allocation#syncAll syncAll()} + * call is necessary after the script data is updated to + * keep the other memory spaces in sync.

* - * By default java side updates are always applied to the script accessable - * memory. If this is not present they are then applied to the various HW - * memory types. A syncAll call is necessary after the script data is update to - * keep the other memory spaces in sync. + *

Allocation data is uploaded in one of two primary ways. For simple + * arrays there are copyFrom() functions that take an array from the control code and + * copy it to the slave memory store. Both type checked and unchecked copies are provided. + * The unchecked variants exist to allow apps to copy over arrays of structures from a + * control language that does not support structures.

* **/ public class Allocation extends BaseObj { diff --git a/graphics/java/android/renderscript/Byte2.java b/graphics/java/android/renderscript/Byte2.java index 6d2994d..7ec6cb0 100644 --- a/graphics/java/android/renderscript/Byte2.java +++ b/graphics/java/android/renderscript/Byte2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs byte2 type back to java applications. + * Class for exposing the native Renderscript byte2 type back to the Android system. * **/ public class Byte2 { diff --git a/graphics/java/android/renderscript/Byte3.java b/graphics/java/android/renderscript/Byte3.java index dd73914..7bcd4b4 100644 --- a/graphics/java/android/renderscript/Byte3.java +++ b/graphics/java/android/renderscript/Byte3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs byte3 type back to java applications. + * Class for exposing the native Renderscript byte3 type back to the Android system. * **/ public class Byte3 { diff --git a/graphics/java/android/renderscript/Byte4.java b/graphics/java/android/renderscript/Byte4.java index ebea589..c6e7f63 100644 --- a/graphics/java/android/renderscript/Byte4.java +++ b/graphics/java/android/renderscript/Byte4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs byte4 type back to java applications. + * Class for exposing the native Renderscript byte4 type back to the Android system. * **/ public class Byte4 { diff --git a/graphics/java/android/renderscript/Element.java b/graphics/java/android/renderscript/Element.java index 10dc35b..4fc419c 100644 --- a/graphics/java/android/renderscript/Element.java +++ b/graphics/java/android/renderscript/Element.java @@ -20,25 +20,26 @@ import java.lang.reflect.Field; import android.util.Log; /** - * Element is the basic data type of RenderScript. An element can be of 2 - * forms. Basic elements contain a single component of data. This can be of - * any of the legal RS types. Examples of basic element types. - * Single float value - * 4 element float vector - * single RGB-565 color - * single unsigned int 16 - * - * Complex elements will contain a list of sub-elements and names. This in - * effect represents a structure of data. The fields can be accessed by name - * from a script or shader. The memory layout is defined and ordered. Data - * alignment is determinied by the most basic primitive type. i.e. a float4 + *

The most basic data type. An element represents one cell of a memory allocation. + * Element is the basic data type of Renderscript. An element can be of two forms: Basic elements or Complex forms. + * Examples of basic elements are:

+ * + *

Complex elements contain a list of sub-elements and names that + * represents a structure of data. The fields can be accessed by name + * from a script or shader. The memory layout is defined and ordered. Data + * alignment is determinied by the most basic primitive type. i.e. a float4 * vector will be alligned to sizeof(float) and not sizeof(float4). The * ordering of elements in memory will be the order in which they were added - * with each component aligned as necessary. No re-ordering will be done. + * with each component aligned as necessary. No re-ordering will be done.

* - * The primary source of elements will be from scripts. A script that exports a - * bind point for a data structure will generate a RS element to represent the - * data exported by the script. + *

The primary source of elements are from scripts. A script that exports a + * bind point for a data structure generates a Renderscript element to represent the + * data exported by the script. The other common source of elements is from bitmap formats.

**/ public class Element extends BaseObj { int mSize; diff --git a/graphics/java/android/renderscript/FieldPacker.java b/graphics/java/android/renderscript/FieldPacker.java index 40628bc..bdda830 100644 --- a/graphics/java/android/renderscript/FieldPacker.java +++ b/graphics/java/android/renderscript/FieldPacker.java @@ -18,8 +18,8 @@ package android.renderscript; /** - * Utility class for packing arguments and structures from java objects to rs - * objects. + * Utility class for packing arguments and structures from Android system objects to + * Renderscript objects. * **/ public class FieldPacker { diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java index 79ee997..b5419a7 100644 --- a/graphics/java/android/renderscript/FileA3D.java +++ b/graphics/java/android/renderscript/FileA3D.java @@ -28,9 +28,9 @@ import android.util.Log; import android.util.TypedValue; /** - * FileA3D allows users to load renderscript objects from files + * FileA3D allows users to load Renderscript objects from files * or resources stored on disk. It could be used to load items - * such as 3d geometry data converted a renderscript format from + * such as 3D geometry data converted to a Renderscript format from * content creation tools. Currently only meshes are supported * in FileA3D. * @@ -66,9 +66,9 @@ public class FileA3D extends BaseObj { } /** - * IndexEntry contains information about one of the renderscript + * IndexEntry contains information about one of the Renderscript * objects inside the file's index. It could be used to query the - * object's type and name and load the object itself if + * object's type and also name and load the object itself if * necessary. */ public static class IndexEntry { diff --git a/graphics/java/android/renderscript/Float2.java b/graphics/java/android/renderscript/Float2.java index 0a099f1..1d4ce36 100644 --- a/graphics/java/android/renderscript/Float2.java +++ b/graphics/java/android/renderscript/Float2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs float2 type back to java applications. + * Class for exposing the native Renderscript float2 type back to the Android system. * **/ public class Float2 { diff --git a/graphics/java/android/renderscript/Float3.java b/graphics/java/android/renderscript/Float3.java index 2ffa326..ffd1135 100644 --- a/graphics/java/android/renderscript/Float3.java +++ b/graphics/java/android/renderscript/Float3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs float3 type back to java applications. + * Class for exposing the native Renderscript float2 type back to the Android system. * **/ public class Float3 { diff --git a/graphics/java/android/renderscript/Float4.java b/graphics/java/android/renderscript/Float4.java index 19d91dc..c7cc3ae 100644 --- a/graphics/java/android/renderscript/Float4.java +++ b/graphics/java/android/renderscript/Float4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs float4 type back to java applications. + * Class for exposing the native Renderscript float2 type back to the Android system. * **/ public class Float4 { diff --git a/graphics/java/android/renderscript/Font.java b/graphics/java/android/renderscript/Font.java index 252ffc1..fa27590 100644 --- a/graphics/java/android/renderscript/Font.java +++ b/graphics/java/android/renderscript/Font.java @@ -30,7 +30,20 @@ import android.util.Log; import android.util.TypedValue; /** - * + *

This class gives users a simple way to draw hardware accelerated text. + * Internally, the glyphs are rendered using the Freetype library and an internal cache of + * rendered glyph bitmaps is maintained. Each font object represents a combination of a typeface, + * and point size. You can create multiple font objects to represent styles such as bold or italic text, + * faces, and different font sizes. During creation, the Android system quieries device's screen DPI to + * ensure proper sizing across multiple device configurations.

+ *

Fonts are rendered using screen-space positions and no state setup beyond binding a + * font to the Renderscript is required. A note of caution on performance, though the state changes + * are transparent to the user, they do happen internally, and it is more efficient to + * render large batches of text in sequence. It is also more efficient to render multiple + * characters at once instead of one by one to improve draw call batching.

+ *

Font color and transparency are not part of the font object and you can freely modify + * them in the script to suit the user's rendering needs. Font colors work as a state machine. + * Every new call to draw text uses the last color set in the script.

**/ public class Font extends BaseObj { diff --git a/graphics/java/android/renderscript/Int2.java b/graphics/java/android/renderscript/Int2.java index 8eceb71..7aaa4e8 100644 --- a/graphics/java/android/renderscript/Int2.java +++ b/graphics/java/android/renderscript/Int2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs int2 type back to java applications. + * Class for exposing the native Renderscript int2 type back to the Android system. * **/ public class Int2 { diff --git a/graphics/java/android/renderscript/Int3.java b/graphics/java/android/renderscript/Int3.java index bbd296e..e5c1cdf 100644 --- a/graphics/java/android/renderscript/Int3.java +++ b/graphics/java/android/renderscript/Int3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs int3 type back to java applications. + * Class for exposing the native Renderscript int3 type back to the Android system. * **/ public class Int3 { diff --git a/graphics/java/android/renderscript/Int4.java b/graphics/java/android/renderscript/Int4.java index c3ae112c..5289a89 100644 --- a/graphics/java/android/renderscript/Int4.java +++ b/graphics/java/android/renderscript/Int4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs int4 type back to java applications. + * Class for exposing the native Renderscript int4 type back to the Android system. * **/ public class Int4 { diff --git a/graphics/java/android/renderscript/Long2.java b/graphics/java/android/renderscript/Long2.java index 834d13c..8590b96 100644 --- a/graphics/java/android/renderscript/Long2.java +++ b/graphics/java/android/renderscript/Long2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * + * Class for exposing the native Renderscript long2 type back to the Android system. **/ public class Long2 { public Long2() { diff --git a/graphics/java/android/renderscript/Long3.java b/graphics/java/android/renderscript/Long3.java index c6d7289..6ae837a 100644 --- a/graphics/java/android/renderscript/Long3.java +++ b/graphics/java/android/renderscript/Long3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * + * Class for exposing the native Renderscript long3 type back to the Android system. **/ public class Long3 { public Long3() { diff --git a/graphics/java/android/renderscript/Long4.java b/graphics/java/android/renderscript/Long4.java index 032c1d3..04c12f2 100644 --- a/graphics/java/android/renderscript/Long4.java +++ b/graphics/java/android/renderscript/Long4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * + * Class for exposing the native Renderscript long4 type back to the Android system. **/ public class Long4 { public Long4() { diff --git a/graphics/java/android/renderscript/Matrix2f.java b/graphics/java/android/renderscript/Matrix2f.java index c9a0ea8..78ff97b 100644 --- a/graphics/java/android/renderscript/Matrix2f.java +++ b/graphics/java/android/renderscript/Matrix2f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs_matrix2x2 type back to java applications. + * Class for exposing the native Renderscript rs_matrix2x2 type back to the Android system. * **/ public class Matrix2f { diff --git a/graphics/java/android/renderscript/Matrix3f.java b/graphics/java/android/renderscript/Matrix3f.java index 2ec8c62..253506d 100644 --- a/graphics/java/android/renderscript/Matrix3f.java +++ b/graphics/java/android/renderscript/Matrix3f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs_matrix3x3 type back to java applications. + * Class for exposing the native Renderscript rs_matrix3x3 type back to the Android system. * **/ public class Matrix3f { diff --git a/graphics/java/android/renderscript/Matrix4f.java b/graphics/java/android/renderscript/Matrix4f.java index 2afd72e..adc1806 100644 --- a/graphics/java/android/renderscript/Matrix4f.java +++ b/graphics/java/android/renderscript/Matrix4f.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs_matrix4x4 type back to java applications. + * Class for exposing the native Renderscript rs_matrix4x4 type back to the Android system. * **/ public class Matrix4f { diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java index 7269cea..bb910cc 100644 --- a/graphics/java/android/renderscript/Mesh.java +++ b/graphics/java/android/renderscript/Mesh.java @@ -22,22 +22,21 @@ import android.util.Config; import android.util.Log; /** - * Mesh class is a container for geometric data displayed in - * renderscript. - * - * Internally, mesh is a collection of allocations that + *

This class is a container for geometric data displayed with + * Renderscript. Internally, a mesh is a collection of allocations that * represent vertex data (positions, normals, texture - * coordinates) and index data such as triangles and lines. - * - * Vertex data could either be interlieved within one - * allocation, provided separately as multiple allocation - * objects or done as a combination of the above. When a + * coordinates) and index data such as triangles and lines.

+ *

+ * Vertex data could either be interleaved within one + * allocation that is provided separately, as multiple allocation + * objects, or done as a combination of both. When a * vertex channel name matches an input in the vertex program, - * renderscript will automatically connect the two together. - * - * Parts of the mesh could be rendered with either explicit + * Renderscript automatically connects the two together. + *

+ *

+ * Parts of the mesh can be rendered with either explicit * index sets or primitive types. - * + *

**/ public class Mesh extends BaseObj { @@ -170,9 +169,9 @@ public class Mesh extends BaseObj { } /** - * Mesh builder object. It starts empty and requires the user to + * Mesh builder object. It starts empty and requires you to * add the types necessary to create vertex and index - * allocations + * allocations. * */ public static class Builder { diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java index 333880d..a48c2e3 100644 --- a/graphics/java/android/renderscript/ProgramFragment.java +++ b/graphics/java/android/renderscript/ProgramFragment.java @@ -22,9 +22,19 @@ import android.util.Log; /** - * ProgramFragment, also know as a fragment shader, describes a - * stage in the graphics pipeline responsible for manipulating - * pixel data in a user-defined way. + *

The Renderscript fragment program, also known as 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, textures inputs, and a Type object + * that describes the constants used by the program. Similar to the vertex programs, + * when an allocation with constant input values is bound to the shader, its values + * are sent to the graphics program automatically.

+ *

The values inside the allocation are not explicitly tracked. If they change between two draw + * calls using the same program object, the runtime needs to be notified of that + * change by calling rsgAllocationSyncAll so it could 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 + * varTex0, the GLSL code inside the program vertex must provide it. + *

* **/ public class ProgramFragment extends Program { diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java index 666a3e6..f99cd7b 100644 --- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java +++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java @@ -22,13 +22,11 @@ import android.util.Log; /** - * ProgramFragmentFixedFunction is a helper class that provides + *

ProgramFragmentFixedFunction is a helper class that provides * a way to make a simple fragment shader without writing any - * GLSL code. - * - * This class allows for display of constant color, interpolated - * color from vertex shader, or combinations of the above - * blended with results of up to two texture lookups. + * GLSL code. This class allows for display of constant color, interpolated + * color from the vertex shader, or combinations of the both + * blended with results of up to two texture lookups.

ProgramStore contains a set of parameters that control how * the graphics hardware handles writes to the framebuffer. - * - * It could be used to: - * - enable/diable depth testing - * - specify wheather depth writes are performed - * - setup various blending modes for use in effects like - * transparency - * - define write masks for color components written into the - * framebuffer + * It could be used to:

+ * * **/ public class ProgramStore extends BaseObj { diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java index a965b81..55653f7 100644 --- a/graphics/java/android/renderscript/ProgramVertex.java +++ b/graphics/java/android/renderscript/ProgramVertex.java @@ -14,6 +14,27 @@ * limitations under the License. */ + /** + *

The Renderscript vertex program, also known as a vertex shader, describes a stage in + * the graphics pipeline responsible for manipulating geometric data in a user-defined way. + * The object is constructed by providing the Renderscript system with the following data:

+ * + * + *

Once the program is created, you bind it to the graphics context, RenderScriptGL, and it will be 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. The Renderscript library 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 Element and the Mesh object 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 runtime takes care of connecting the + * two. Unlike OpenGL, there is no need to link the vertex and fragment programs.

+ * + **/ package android.renderscript; diff --git a/graphics/java/android/renderscript/RSSurfaceView.java b/graphics/java/android/renderscript/RSSurfaceView.java index be893bb..199952c 100644 --- a/graphics/java/android/renderscript/RSSurfaceView.java +++ b/graphics/java/android/renderscript/RSSurfaceView.java @@ -30,7 +30,7 @@ import android.view.SurfaceHolder; import android.view.SurfaceView; /** - * + * The Surface View for a graphics renderscript (RenderScriptGL) to draw on. */ public class RSSurfaceView extends SurfaceView implements SurfaceHolder.Callback { private SurfaceHolder mSurfaceHolder; diff --git a/graphics/java/android/renderscript/Sampler.java b/graphics/java/android/renderscript/Sampler.java index c656d75..8ee4d72 100644 --- a/graphics/java/android/renderscript/Sampler.java +++ b/graphics/java/android/renderscript/Sampler.java @@ -29,8 +29,8 @@ import android.graphics.Bitmap; import android.graphics.BitmapFactory; /** - * Sampler object which defines how data is extracted from textures. Samplers - * are attached to Program objects (currently only fragment) when those objects + * Sampler object which defines how data is extracted from textures. Samplers + * are attached to Program objects (currently only ProgramFragment) when those objects * need to access texture data. **/ public class Sampler extends BaseObj { diff --git a/graphics/java/android/renderscript/Short2.java b/graphics/java/android/renderscript/Short2.java index 82d897e..7094edd 100644 --- a/graphics/java/android/renderscript/Short2.java +++ b/graphics/java/android/renderscript/Short2.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs short2 type back to java applications. + * Class for exposing the native Renderscript Short2 type back to the Android system. * **/ public class Short2 { diff --git a/graphics/java/android/renderscript/Short3.java b/graphics/java/android/renderscript/Short3.java index 00da574..f34500c 100644 --- a/graphics/java/android/renderscript/Short3.java +++ b/graphics/java/android/renderscript/Short3.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs short3 type back to java applications. + * Class for exposing the native Renderscript short3 type back to the Android system. * **/ public class Short3 { diff --git a/graphics/java/android/renderscript/Short4.java b/graphics/java/android/renderscript/Short4.java index 450258d..5698fee 100644 --- a/graphics/java/android/renderscript/Short4.java +++ b/graphics/java/android/renderscript/Short4.java @@ -21,7 +21,7 @@ import android.util.Log; /** - * Class for exposing the rs short4 type back to java applications. + * Class for exposing the native Renderscript short4 type back to the Android system. * **/ public class Short4 { diff --git a/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java index bec76d0..9979e2a 100644 --- a/graphics/java/android/renderscript/Type.java +++ b/graphics/java/android/renderscript/Type.java @@ -21,19 +21,19 @@ import java.lang.reflect.Field; import android.util.Log; /** - * Type is an allocation template. It consists of an Element and one or more - * dimensions. It describes only the layout of memory but does not allocate and - * storage for the data thus described. + *

Type is an allocation template. It consists of an Element and one or more + * dimensions. It describes only the layout of memory but does not allocate any + * storage for the data that is described.

* - * A Type consists of several dimensions. Those are X, Y, Z, LOD (level of + *

A Type consists of several dimensions. Those are X, Y, Z, LOD (level of * detail), Faces (faces of a cube map). The X,Y,Z dimensions can be assigned * any positive integral value within the constraints of available memory. A * single dimension allocation would have an X dimension of greater than zero * while the Y and Z dimensions would be zero to indicate not present. In this * regard an allocation of x=10, y=1 would be considered 2 dimensionsal while - * x=10, y=0 would be considered 1 dimensional. + * x=10, y=0 would be considered 1 dimensional.

* - * The LOD and Faces dimensions are booleans to indicate present or not present. + *

The LOD and Faces dimensions are booleans to indicate present or not present.

* **/ public class Type extends BaseObj { diff --git a/graphics/java/android/renderscript/package.html b/graphics/java/android/renderscript/package.html new file mode 100644 index 0000000..36a24ff --- /dev/null +++ b/graphics/java/android/renderscript/package.html @@ -0,0 +1,85 @@ + + +

The Renderscript rendering and computational APIs offer a low-level, high performance means of +carrying out mathematical calculations and 3D graphics rendering. An example of Renderscript in +applications include the 3D carousel view that is present in Android 3.0 applications such as the +Books and YouTube applications. This API is intended for developers who are comfortable working with +native code and want to maximize their performance critical applications.

+ +

Renderscript adopts a control and slave architecture where the low-level native code is controlled by the +higher level Android system that runs in the virtual machine (VM). The VM code handles resource +allocation and lifecycle management of the Renderscript enabled application and calls the Renderscript +code through high level entry points. The Android build tools generate these entry points through reflection on +the native Renderscript code, which you write in C (C99 standard). The Renderscript code +does the intensive computation and returns the result back to the Android VM.

+ +

You can find the Renderscript native +APIs in the <sdk_root>/platforms/android-3.0/renderscript directory. +The Android system APIs are broken into a few main groups:

+ +

Core

+

These classes are used internally by the system for memory allocation. They are used by the classes that +are generated by the build tools:

+ + + +

Data Types

+

These data types are used by the classes that are generated +by the build tools. They are the reflected counterparts of the native data types that +are defined by the native Renderscript APIs and used by your Renderscript code. The +classes include:

+ + +

For example, if you declared the following struct in your .rs Renderscript file:

+ +
struct Hello { float3 position; rs_matrix4x4 transform; }
+ +

The build tools generate a class through reflection that looks like the following:

+
+class Hello {
+    static public class Item {
+        Float4 position;
+        Matrix4f transform;
+    }
+Element createElement(RenderScript rs) {
+        Element.Builder eb = new Element.Builder(rs);
+        eb.add(Element.F32_3(rs), "position");
+        eb.add(Element.MATRIX_4X4(rs), "transform");
+        return eb.create();
+    }
+}
+
+ +

Graphics

+

These classes are specific to graphics Renderscripts and support a typical rendering +pipeline.

+ + +

+

+For information on how to create an application that uses Renderscript, and also the +see 3D with +Renderscript dev guide. +

+ + -- cgit v1.1