diff options
17 files changed, 1462 insertions, 35 deletions
diff --git a/api/current.txt b/api/current.txt index f049f95..d1a904a 100644 --- a/api/current.txt +++ b/api/current.txt @@ -19713,6 +19713,29 @@ package android.renderscript { method public void skip(int); } + public deprecated class FileA3D extends android.renderscript.BaseObj { + method public static deprecated android.renderscript.FileA3D createFromAsset(android.renderscript.RenderScript, android.content.res.AssetManager, java.lang.String); + method public static deprecated android.renderscript.FileA3D createFromFile(android.renderscript.RenderScript, java.lang.String); + method public static deprecated android.renderscript.FileA3D createFromFile(android.renderscript.RenderScript, java.io.File); + method public static deprecated android.renderscript.FileA3D createFromResource(android.renderscript.RenderScript, android.content.res.Resources, int); + method public deprecated android.renderscript.FileA3D.IndexEntry getIndexEntry(int); + method public deprecated int getIndexEntryCount(); + } + + public static final deprecated class FileA3D.EntryType extends java.lang.Enum { + method public static android.renderscript.FileA3D.EntryType valueOf(java.lang.String); + method public static final android.renderscript.FileA3D.EntryType[] values(); + enum_constant public static final deprecated android.renderscript.FileA3D.EntryType MESH; + enum_constant public static final deprecated android.renderscript.FileA3D.EntryType UNKNOWN; + } + + public static deprecated class FileA3D.IndexEntry { + method public deprecated android.renderscript.FileA3D.EntryType getEntryType(); + method public deprecated android.renderscript.Mesh getMesh(); + method public deprecated java.lang.String getName(); + method public deprecated android.renderscript.BaseObj getObject(); + } + public class Float2 { ctor public Float2(); ctor public Float2(float, float); @@ -19737,6 +19760,23 @@ package android.renderscript { field public float z; } + public deprecated class Font extends android.renderscript.BaseObj { + method public static deprecated android.renderscript.Font create(android.renderscript.RenderScript, android.content.res.Resources, java.lang.String, android.renderscript.Font.Style, float); + method public static deprecated android.renderscript.Font createFromAsset(android.renderscript.RenderScript, android.content.res.Resources, java.lang.String, float); + method public static deprecated android.renderscript.Font createFromFile(android.renderscript.RenderScript, android.content.res.Resources, java.lang.String, float); + method public static deprecated android.renderscript.Font createFromFile(android.renderscript.RenderScript, android.content.res.Resources, java.io.File, float); + method public static deprecated android.renderscript.Font createFromResource(android.renderscript.RenderScript, android.content.res.Resources, int, float); + } + + public static final deprecated class Font.Style extends java.lang.Enum { + method public static android.renderscript.Font.Style valueOf(java.lang.String); + method public static final android.renderscript.Font.Style[] values(); + enum_constant public static final deprecated android.renderscript.Font.Style BOLD; + enum_constant public static final deprecated android.renderscript.Font.Style BOLD_ITALIC; + enum_constant public static final deprecated android.renderscript.Font.Style ITALIC; + enum_constant public static final deprecated android.renderscript.Font.Style NORMAL; + } + public class Int2 { ctor public Int2(); ctor public Int2(int, int); @@ -19851,6 +19891,245 @@ package android.renderscript { method public void transpose(); } + public deprecated class Mesh extends android.renderscript.BaseObj { + method public deprecated android.renderscript.Allocation getIndexSetAllocation(int); + method public deprecated android.renderscript.Mesh.Primitive getPrimitive(int); + method public deprecated int getPrimitiveCount(); + method public deprecated android.renderscript.Allocation getVertexAllocation(int); + method public deprecated int getVertexAllocationCount(); + } + + public static deprecated class Mesh.AllocationBuilder { + ctor public deprecated Mesh.AllocationBuilder(android.renderscript.RenderScript); + method public deprecated android.renderscript.Mesh.AllocationBuilder addIndexSetAllocation(android.renderscript.Allocation, android.renderscript.Mesh.Primitive); + method public deprecated android.renderscript.Mesh.AllocationBuilder addIndexSetType(android.renderscript.Mesh.Primitive); + method public deprecated android.renderscript.Mesh.AllocationBuilder addVertexAllocation(android.renderscript.Allocation) throws java.lang.IllegalStateException; + method public deprecated android.renderscript.Mesh create(); + method public deprecated int getCurrentIndexSetIndex(); + method public deprecated int getCurrentVertexTypeIndex(); + } + + public static deprecated class Mesh.Builder { + ctor public deprecated Mesh.Builder(android.renderscript.RenderScript, int); + method public deprecated android.renderscript.Mesh.Builder addIndexSetType(android.renderscript.Type, android.renderscript.Mesh.Primitive); + method public deprecated android.renderscript.Mesh.Builder addIndexSetType(android.renderscript.Mesh.Primitive); + method public deprecated android.renderscript.Mesh.Builder addIndexSetType(android.renderscript.Element, int, android.renderscript.Mesh.Primitive); + method public deprecated android.renderscript.Mesh.Builder addVertexType(android.renderscript.Type) throws java.lang.IllegalStateException; + method public deprecated android.renderscript.Mesh.Builder addVertexType(android.renderscript.Element, int) throws java.lang.IllegalStateException; + method public deprecated android.renderscript.Mesh create(); + method public deprecated int getCurrentIndexSetIndex(); + method public deprecated int getCurrentVertexTypeIndex(); + } + + public static final deprecated class Mesh.Primitive extends java.lang.Enum { + method public static android.renderscript.Mesh.Primitive valueOf(java.lang.String); + method public static final android.renderscript.Mesh.Primitive[] values(); + enum_constant public static final deprecated android.renderscript.Mesh.Primitive LINE; + enum_constant public static final deprecated android.renderscript.Mesh.Primitive LINE_STRIP; + enum_constant public static final deprecated android.renderscript.Mesh.Primitive POINT; + enum_constant public static final deprecated android.renderscript.Mesh.Primitive TRIANGLE; + enum_constant public static final deprecated android.renderscript.Mesh.Primitive TRIANGLE_FAN; + enum_constant public static final deprecated android.renderscript.Mesh.Primitive TRIANGLE_STRIP; + } + + public static deprecated class Mesh.TriangleMeshBuilder { + ctor public deprecated Mesh.TriangleMeshBuilder(android.renderscript.RenderScript, int, int); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder addTriangle(int, int, int); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder addVertex(float, float); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder addVertex(float, float, float); + method public deprecated android.renderscript.Mesh create(boolean); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder setColor(float, float, float, float); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder setNormal(float, float, float); + method public deprecated android.renderscript.Mesh.TriangleMeshBuilder setTexture(float, float); + field public static final deprecated int COLOR = 1; // 0x1 + field public static final deprecated int NORMAL = 2; // 0x2 + field public static final deprecated int TEXTURE_0 = 256; // 0x100 + } + + public class Program extends android.renderscript.BaseObj { + method public void bindConstants(android.renderscript.Allocation, int); + method public void bindSampler(android.renderscript.Sampler, int) throws java.lang.IllegalArgumentException; + method public void bindTexture(android.renderscript.Allocation, int) throws java.lang.IllegalArgumentException; + method public android.renderscript.Type getConstant(int); + method public int getConstantCount(); + method public int getTextureCount(); + method public java.lang.String getTextureName(int); + method public android.renderscript.Program.TextureType getTextureType(int); + } + + public static class Program.BaseProgramBuilder { + ctor protected Program.BaseProgramBuilder(android.renderscript.RenderScript); + method public android.renderscript.Program.BaseProgramBuilder addConstant(android.renderscript.Type) throws java.lang.IllegalStateException; + method public android.renderscript.Program.BaseProgramBuilder addTexture(android.renderscript.Program.TextureType) throws java.lang.IllegalArgumentException; + method public android.renderscript.Program.BaseProgramBuilder addTexture(android.renderscript.Program.TextureType, java.lang.String) throws java.lang.IllegalArgumentException; + method public int getCurrentConstantIndex(); + method public int getCurrentTextureIndex(); + method protected void initProgram(android.renderscript.Program); + method public android.renderscript.Program.BaseProgramBuilder setShader(java.lang.String); + method public android.renderscript.Program.BaseProgramBuilder setShader(android.content.res.Resources, int); + } + + public static final class Program.TextureType extends java.lang.Enum { + method public static android.renderscript.Program.TextureType valueOf(java.lang.String); + method public static final android.renderscript.Program.TextureType[] values(); + enum_constant public static final android.renderscript.Program.TextureType TEXTURE_2D; + enum_constant public static final android.renderscript.Program.TextureType TEXTURE_CUBE; + } + + public deprecated class ProgramFragment extends android.renderscript.Program { + } + + public static deprecated class ProgramFragment.Builder extends android.renderscript.Program.BaseProgramBuilder { + ctor public deprecated ProgramFragment.Builder(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramFragment create(); + } + + public deprecated class ProgramFragmentFixedFunction extends android.renderscript.ProgramFragment { + } + + public static deprecated class ProgramFragmentFixedFunction.Builder { + ctor public deprecated ProgramFragmentFixedFunction.Builder(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramFragmentFixedFunction create(); + method public deprecated android.renderscript.ProgramFragmentFixedFunction.Builder setPointSpriteTexCoordinateReplacement(boolean); + method public deprecated android.renderscript.ProgramFragmentFixedFunction.Builder setTexture(android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode, android.renderscript.ProgramFragmentFixedFunction.Builder.Format, int) throws java.lang.IllegalArgumentException; + method public deprecated android.renderscript.ProgramFragmentFixedFunction.Builder setVaryingColor(boolean); + field public static final deprecated int MAX_TEXTURE = 2; // 0x2 + } + + public static final deprecated class ProgramFragmentFixedFunction.Builder.EnvMode extends java.lang.Enum { + method public static android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode valueOf(java.lang.String); + method public static final android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode[] values(); + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode DECAL; + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode MODULATE; + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.EnvMode REPLACE; + } + + public static final deprecated class ProgramFragmentFixedFunction.Builder.Format extends java.lang.Enum { + method public static android.renderscript.ProgramFragmentFixedFunction.Builder.Format valueOf(java.lang.String); + method public static final android.renderscript.ProgramFragmentFixedFunction.Builder.Format[] values(); + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.Format ALPHA; + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.Format LUMINANCE_ALPHA; + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.Format RGB; + enum_constant public static final deprecated android.renderscript.ProgramFragmentFixedFunction.Builder.Format RGBA; + } + + public deprecated class ProgramRaster extends android.renderscript.BaseObj { + method public static deprecated android.renderscript.ProgramRaster CULL_BACK(android.renderscript.RenderScript); + method public static deprecated android.renderscript.ProgramRaster CULL_FRONT(android.renderscript.RenderScript); + method public static deprecated android.renderscript.ProgramRaster CULL_NONE(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramRaster.CullMode getCullMode(); + method public deprecated boolean isPointSpriteEnabled(); + } + + public static deprecated class ProgramRaster.Builder { + ctor public deprecated ProgramRaster.Builder(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramRaster create(); + method public deprecated android.renderscript.ProgramRaster.Builder setCullMode(android.renderscript.ProgramRaster.CullMode); + method public deprecated android.renderscript.ProgramRaster.Builder setPointSpriteEnabled(boolean); + } + + public static final deprecated class ProgramRaster.CullMode extends java.lang.Enum { + method public static android.renderscript.ProgramRaster.CullMode valueOf(java.lang.String); + method public static final android.renderscript.ProgramRaster.CullMode[] values(); + enum_constant public static final deprecated android.renderscript.ProgramRaster.CullMode BACK; + enum_constant public static final deprecated android.renderscript.ProgramRaster.CullMode FRONT; + enum_constant public static final deprecated android.renderscript.ProgramRaster.CullMode NONE; + } + + public class ProgramStore extends android.renderscript.BaseObj { + method public static android.renderscript.ProgramStore BLEND_ALPHA_DEPTH_NONE(android.renderscript.RenderScript); + method public static android.renderscript.ProgramStore BLEND_ALPHA_DEPTH_TEST(android.renderscript.RenderScript); + method public static android.renderscript.ProgramStore BLEND_NONE_DEPTH_NONE(android.renderscript.RenderScript); + method public static android.renderscript.ProgramStore BLEND_NONE_DEPTH_TEST(android.renderscript.RenderScript); + method public android.renderscript.ProgramStore.BlendDstFunc getBlendDstFunc(); + method public android.renderscript.ProgramStore.BlendSrcFunc getBlendSrcFunc(); + method public android.renderscript.ProgramStore.DepthFunc getDepthFunc(); + method public boolean isColorMaskAlphaEnabled(); + method public boolean isColorMaskBlueEnabled(); + method public boolean isColorMaskGreenEnabled(); + method public boolean isColorMaskRedEnabled(); + method public boolean isDepthMaskEnabled(); + method public boolean isDitherEnabled(); + } + + public static final class ProgramStore.BlendDstFunc extends java.lang.Enum { + method public static android.renderscript.ProgramStore.BlendDstFunc valueOf(java.lang.String); + method public static final android.renderscript.ProgramStore.BlendDstFunc[] values(); + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc DST_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc ONE; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc ONE_MINUS_DST_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc ONE_MINUS_SRC_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc ONE_MINUS_SRC_COLOR; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc SRC_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc SRC_COLOR; + enum_constant public static final android.renderscript.ProgramStore.BlendDstFunc ZERO; + } + + public static final class ProgramStore.BlendSrcFunc extends java.lang.Enum { + method public static android.renderscript.ProgramStore.BlendSrcFunc valueOf(java.lang.String); + method public static final android.renderscript.ProgramStore.BlendSrcFunc[] values(); + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc DST_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc DST_COLOR; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc ONE; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc ONE_MINUS_DST_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc ONE_MINUS_DST_COLOR; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc ONE_MINUS_SRC_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc SRC_ALPHA; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc SRC_ALPHA_SATURATE; + enum_constant public static final android.renderscript.ProgramStore.BlendSrcFunc ZERO; + } + + public static class ProgramStore.Builder { + ctor public ProgramStore.Builder(android.renderscript.RenderScript); + method public android.renderscript.ProgramStore create(); + method public android.renderscript.ProgramStore.Builder setBlendFunc(android.renderscript.ProgramStore.BlendSrcFunc, android.renderscript.ProgramStore.BlendDstFunc); + method public android.renderscript.ProgramStore.Builder setColorMaskEnabled(boolean, boolean, boolean, boolean); + method public android.renderscript.ProgramStore.Builder setDepthFunc(android.renderscript.ProgramStore.DepthFunc); + method public android.renderscript.ProgramStore.Builder setDepthMaskEnabled(boolean); + method public android.renderscript.ProgramStore.Builder setDitherEnabled(boolean); + } + + public static final class ProgramStore.DepthFunc extends java.lang.Enum { + method public static android.renderscript.ProgramStore.DepthFunc valueOf(java.lang.String); + method public static final android.renderscript.ProgramStore.DepthFunc[] values(); + enum_constant public static final android.renderscript.ProgramStore.DepthFunc ALWAYS; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc EQUAL; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc GREATER; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc GREATER_OR_EQUAL; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc LESS; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc LESS_OR_EQUAL; + enum_constant public static final android.renderscript.ProgramStore.DepthFunc NOT_EQUAL; + } + + public deprecated class ProgramVertex extends android.renderscript.Program { + method public deprecated android.renderscript.Element getInput(int); + method public deprecated int getInputCount(); + } + + public static deprecated class ProgramVertex.Builder extends android.renderscript.Program.BaseProgramBuilder { + ctor public deprecated ProgramVertex.Builder(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramVertex.Builder addInput(android.renderscript.Element) throws java.lang.IllegalStateException; + method public deprecated android.renderscript.ProgramVertex create(); + } + + public deprecated class ProgramVertexFixedFunction extends android.renderscript.ProgramVertex { + method public deprecated void bindConstants(android.renderscript.ProgramVertexFixedFunction.Constants); + } + + public static deprecated class ProgramVertexFixedFunction.Builder { + ctor public deprecated ProgramVertexFixedFunction.Builder(android.renderscript.RenderScript); + method public deprecated android.renderscript.ProgramVertexFixedFunction create(); + method public deprecated android.renderscript.ProgramVertexFixedFunction.Builder setTextureMatrixEnable(boolean); + } + + public static deprecated class ProgramVertexFixedFunction.Constants { + ctor public deprecated ProgramVertexFixedFunction.Constants(android.renderscript.RenderScript); + method public deprecated void destroy(); + method public deprecated void setModelview(android.renderscript.Matrix4f); + method public deprecated void setProjection(android.renderscript.Matrix4f); + method public deprecated void setTexture(android.renderscript.Matrix4f); + } + public class RSDriverException extends android.renderscript.RSRuntimeException { ctor public RSDriverException(java.lang.String); } @@ -19867,6 +20146,35 @@ package android.renderscript { ctor public RSRuntimeException(java.lang.String); } + public deprecated class RSSurfaceView extends android.view.SurfaceView implements android.view.SurfaceHolder.Callback { + ctor public deprecated RSSurfaceView(android.content.Context); + ctor public deprecated RSSurfaceView(android.content.Context, android.util.AttributeSet); + method public deprecated android.renderscript.RenderScriptGL createRenderScriptGL(android.renderscript.RenderScriptGL.SurfaceConfig); + method public deprecated void destroyRenderScriptGL(); + method public deprecated android.renderscript.RenderScriptGL getRenderScriptGL(); + method public deprecated void pause(); + method public deprecated void resume(); + method public deprecated void setRenderScriptGL(android.renderscript.RenderScriptGL); + method public deprecated void surfaceChanged(android.view.SurfaceHolder, int, int, int); + method public deprecated void surfaceCreated(android.view.SurfaceHolder); + method public deprecated void surfaceDestroyed(android.view.SurfaceHolder); + } + + public deprecated class RSTextureView extends android.view.TextureView implements android.view.TextureView.SurfaceTextureListener { + ctor public deprecated RSTextureView(android.content.Context); + ctor public deprecated RSTextureView(android.content.Context, android.util.AttributeSet); + method public deprecated android.renderscript.RenderScriptGL createRenderScriptGL(android.renderscript.RenderScriptGL.SurfaceConfig); + method public deprecated void destroyRenderScriptGL(); + method public deprecated android.renderscript.RenderScriptGL getRenderScriptGL(); + method public deprecated void onSurfaceTextureAvailable(android.graphics.SurfaceTexture, int, int); + method public deprecated boolean onSurfaceTextureDestroyed(android.graphics.SurfaceTexture); + method public deprecated void onSurfaceTextureSizeChanged(android.graphics.SurfaceTexture, int, int); + method public deprecated void onSurfaceTextureUpdated(android.graphics.SurfaceTexture); + method public deprecated void pause(); + method public deprecated void resume(); + method public deprecated void setRenderScriptGL(android.renderscript.RenderScriptGL); + } + public class RenderScript { method public void contextDump(); method public static android.renderscript.RenderScript create(android.content.Context); @@ -19910,6 +20218,30 @@ package android.renderscript { field protected int mLength; } + public deprecated class RenderScriptGL extends android.renderscript.RenderScript { + ctor public deprecated RenderScriptGL(android.content.Context, android.renderscript.RenderScriptGL.SurfaceConfig); + method public deprecated void bindProgramFragment(android.renderscript.ProgramFragment); + method public deprecated void bindProgramRaster(android.renderscript.ProgramRaster); + method public deprecated void bindProgramStore(android.renderscript.ProgramStore); + method public deprecated void bindProgramVertex(android.renderscript.ProgramVertex); + method public deprecated void bindRootScript(android.renderscript.Script); + method public deprecated int getHeight(); + method public deprecated int getWidth(); + method public deprecated void pause(); + method public deprecated void resume(); + method public deprecated void setSurface(android.view.SurfaceHolder, int, int); + method public deprecated void setSurfaceTexture(android.graphics.SurfaceTexture, int, int); + } + + public static deprecated class RenderScriptGL.SurfaceConfig { + ctor public deprecated RenderScriptGL.SurfaceConfig(); + ctor public deprecated RenderScriptGL.SurfaceConfig(android.renderscript.RenderScriptGL.SurfaceConfig); + method public deprecated void setAlpha(int, int); + method public deprecated void setColor(int, int); + method public deprecated void setDepth(int, int); + method public deprecated void setSamples(int, int, float); + } + public class Sampler extends android.renderscript.BaseObj { method public static android.renderscript.Sampler CLAMP_LINEAR(android.renderscript.RenderScript); method public static android.renderscript.Sampler CLAMP_LINEAR_MIP_LINEAR(android.renderscript.RenderScript); diff --git a/docs/html/about/versions/android-4.0.jd b/docs/html/about/versions/android-4.0.jd index 868227a..f2fd0c4 100644 --- a/docs/html/about/versions/android-4.0.jd +++ b/docs/html/about/versions/android-4.0.jd @@ -122,7 +122,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 @@ -327,7 +327,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, @@ -452,7 +452,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 @@ -495,7 +495,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 @@ -775,7 +775,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 @@ -1022,6 +1022,46 @@ 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> @@ -1718,7 +1758,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> @@ -1741,7 +1781,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/guide/topics/graphics/renderscript/graphics.jd b/docs/html/guide/topics/graphics/renderscript/graphics.jd new file mode 100644 index 0000000..58676ea --- /dev/null +++ b/docs/html/guide/topics/graphics/renderscript/graphics.jd @@ -0,0 +1,994 @@ +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/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java index 8b0222a..42b508b 100644 --- a/graphics/java/android/renderscript/FileA3D.java +++ b/graphics/java/android/renderscript/FileA3D.java @@ -28,7 +28,6 @@ import android.util.Log; import android.util.TypedValue; /** - * @hide * @deprecated in API 16 * FileA3D allows users to load Renderscript objects from files * or resources stored on disk. It could be used to load items diff --git a/graphics/java/android/renderscript/Font.java b/graphics/java/android/renderscript/Font.java index 1a8d5bf..8a49abb 100644 --- a/graphics/java/android/renderscript/Font.java +++ b/graphics/java/android/renderscript/Font.java @@ -30,9 +30,8 @@ import android.util.Log; import android.util.TypedValue; /** - * @hide * @deprecated in API 16 - * <p>This class gives users a simple way to draw hardware accelerated text. + * <p>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, @@ -44,7 +43,7 @@ import android.util.TypedValue; * 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.</p> * <p>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. + * 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.</p> **/ public class Font extends BaseObj { diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java index d0d383d..7210513 100644 --- a/graphics/java/android/renderscript/Mesh.java +++ b/graphics/java/android/renderscript/Mesh.java @@ -21,7 +21,6 @@ import java.util.Vector; import android.util.Log; /** - * @hide * @deprecated in API 16 * <p>This class is a container for geometric data displayed with * Renderscript. Internally, a mesh is a collection of allocations that diff --git a/graphics/java/android/renderscript/Program.java b/graphics/java/android/renderscript/Program.java index 9bd103e..d9f64c6 100644 --- a/graphics/java/android/renderscript/Program.java +++ b/graphics/java/android/renderscript/Program.java @@ -26,7 +26,6 @@ import android.util.Log; /** - * @hide * * Program is a base class for all the objects that modify * various stages of the graphics pipeline diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java index dd0f9f5..69968ac 100644 --- a/graphics/java/android/renderscript/ProgramFragment.java +++ b/graphics/java/android/renderscript/ProgramFragment.java @@ -21,7 +21,6 @@ import android.util.Log; /** - * @hide * @deprecated in API 16 * <p>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 diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java index 8ae1777..848c5a3 100644 --- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java +++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java @@ -21,7 +21,6 @@ import android.util.Log; /** - * @hide * @deprecated in API 16 * <p>ProgramFragmentFixedFunction is a helper class that provides * a way to make a simple fragment shader without writing any diff --git a/graphics/java/android/renderscript/ProgramRaster.java b/graphics/java/android/renderscript/ProgramRaster.java index 216cb4e..c44521b 100644 --- a/graphics/java/android/renderscript/ProgramRaster.java +++ b/graphics/java/android/renderscript/ProgramRaster.java @@ -21,7 +21,6 @@ import android.util.Log; /** - * @hide * @deprecated in API 16 * Program raster is primarily used to specify whether point sprites are enabled and to control * the culling mode. By default, back faces are culled. diff --git a/graphics/java/android/renderscript/ProgramStore.java b/graphics/java/android/renderscript/ProgramStore.java index dac9e76..d0fd6e5 100644 --- a/graphics/java/android/renderscript/ProgramStore.java +++ b/graphics/java/android/renderscript/ProgramStore.java @@ -21,7 +21,6 @@ import android.util.Log; /** - * @hide * <p>ProgramStore contains a set of parameters that control how * the graphics hardware handles writes to the framebuffer. * It could be used to:</p> diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java index 50e32f6..2bd5124 100644 --- a/graphics/java/android/renderscript/ProgramVertex.java +++ b/graphics/java/android/renderscript/ProgramVertex.java @@ -14,8 +14,7 @@ * limitations under the License. */ -/** - * @hide + /** * <p>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:</p> @@ -44,7 +43,6 @@ import android.util.Log; /** - * @hide * @deprecated in API 16 * ProgramVertex, also know as a vertex shader, describes a * stage in the graphics pipeline responsible for manipulating @@ -78,15 +76,14 @@ public class ProgramVertex extends Program { } /** - * @hide - * @deprecated in API 16 - * Builder class for creating ProgramVertex objects. - * The builder starts empty and the user must minimally provide - * the GLSL shader code, and the varying inputs. Constant, or - * uniform parameters to the shader may optionally be provided as - * well. - * - **/ + * @deprecated in API 16 + * Builder class for creating ProgramVertex objects. + * The builder starts empty and the user must minimally provide + * the GLSL shader code, and the varying inputs. Constant, or + * uniform parameters to the shader may optionally be provided as + * well. + * + **/ public static class Builder extends BaseProgramBuilder { /** * @deprecated in API 16 diff --git a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java index ad486f3..88cade4 100644 --- a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java +++ b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java @@ -22,7 +22,6 @@ import android.util.Log; /** - * @hide * @deprecated in API 16 * ProgramVertexFixedFunction is a helper class that provides a * simple way to create a fixed function emulation vertex shader diff --git a/graphics/java/android/renderscript/RSSurfaceView.java b/graphics/java/android/renderscript/RSSurfaceView.java index 3c6c720..82ed95c 100644 --- a/graphics/java/android/renderscript/RSSurfaceView.java +++ b/graphics/java/android/renderscript/RSSurfaceView.java @@ -30,7 +30,6 @@ import android.view.SurfaceHolder; import android.view.SurfaceView; /** - * @hide * @deprecated in API 16 * The Surface View for a graphics renderscript (RenderScriptGL) to draw on. * diff --git a/graphics/java/android/renderscript/RSTextureView.java b/graphics/java/android/renderscript/RSTextureView.java index 7eeeeae..ed04000 100644 --- a/graphics/java/android/renderscript/RSTextureView.java +++ b/graphics/java/android/renderscript/RSTextureView.java @@ -29,7 +29,6 @@ import android.util.Log; import android.view.TextureView; /** - * @hide * @deprecated in API 16 * The Texture View for a graphics renderscript (RenderScriptGL) * to draw on. diff --git a/graphics/java/android/renderscript/RenderScriptGL.java b/graphics/java/android/renderscript/RenderScriptGL.java index 52034b1..5269405 100644 --- a/graphics/java/android/renderscript/RenderScriptGL.java +++ b/graphics/java/android/renderscript/RenderScriptGL.java @@ -29,7 +29,6 @@ import android.view.SurfaceHolder; import android.view.SurfaceView; /** - * @hide * @deprecated in API 16 * The Graphics derivitive of Renderscript. Extends the basic context to add a * root script which is the display window for graphical output. When the diff --git a/graphics/java/android/renderscript/package.html b/graphics/java/android/renderscript/package.html index eb178c1..5eab23c 100644 --- a/graphics/java/android/renderscript/package.html +++ b/graphics/java/android/renderscript/package.html @@ -1,10 +1,86 @@ <HTML> <BODY> -<p>RenderScript provides support for high-performance computation across heterogeneous processors.</p> +<p>The Renderscript rendering and computational APIs offer a low-level, high performance means of +carrying out mathematical calculations and 3D graphics rendering.</p> <p>For more information, see the -<a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a> developer guide.</p> +<a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a> developer guide.</p> {@more} +<p>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.</p> + +<p>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.</p> + +<p>You can find the Renderscript native +APIs in the <code><sdk_root>/platforms/android-11/renderscript</code> directory. +The Android system APIs are broken into a few main groups:</p> + +<h4>Core</h4> +<p>These classes are used internally by the system for memory allocation. They are used by the classes that +are generated by the build tools:</p> +<ul> + <li>Allocation</li> + <li>Element</li> + <li>Type</li> + <li>Script</li> +</ul> + + +<h4>Data Types</h4> +<p>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:</p> +<ul> + <li>Byte2, Byte3, and Byte4</li> + <li>Float2, Float3, Float4</li> + <li>Int2, Int3, Int4</li> + <li>Long2, Long3, Long4</li> + <li>Matrix2f, Matrix3f, Matrix4f</li> + <li>Short2, Short3, Short4</li> +</ul> + +<p>For example, if you declared the following struct in your .rs Renderscript file:</p> + +<pre>struct Hello { float3 position; rs_matrix4x4 transform; }</pre> + +<p>The build tools generate a class through reflection that looks like the following:</p> +<pre> +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(); + } +} +</pre> + +<h4>Graphics</h4> +<p>These classes are specific to graphics Renderscripts and support a typical rendering +pipeline.</p> +<ul> +<li>Mesh</li> +<li>ProgramFragment</li> +<li>ProgramRaster</li> +<li>ProgramStore</li> +<li>ProgramVertex</li> +<li>RSSurfaceView</li> +<li>Sampler</li> +</ul> + +</p> </BODY> </HTML> |