Documentation
Change-Id: Idb5f87f9d2c0f7fb4677b1b45c232502d66b4668
diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index 6b309e1..b15121a 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -479,26 +479,67 @@
mBitmapOptions.inScaled = false;
}
- static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mc, int usage) {
+ /**
+ *
+ * @param type renderscript type describing data layout
+ * @param mips specifies desired mipmap behaviour for the
+ * allocation
+ * @param usage bit field specifying how the allocation is
+ * utilized
+ */
+ static public Allocation createTyped(RenderScript rs, Type type, MipmapControl mips, int usage) {
rs.validate();
if (type.getID() == 0) {
throw new RSInvalidStateException("Bad Type");
}
- int id = rs.nAllocationCreateTyped(type.getID(), mc.mID, usage);
+ int id = rs.nAllocationCreateTyped(type.getID(), mips.mID, usage);
if (id == 0) {
throw new RSRuntimeException("Allocation creation failed.");
}
return new Allocation(id, rs, type, usage);
}
+ /**
+ * Creates a renderscript allocation with the size specified by
+ * the type and no mipmaps generated by default
+ *
+ * @param rs
+ * @param type renderscript type describing data layout
+ * @param usage bit field specifying how the allocation is
+ * utilized
+ *
+ * @return allocation
+ */
static public Allocation createTyped(RenderScript rs, Type type, int usage) {
return createTyped(rs, type, MipmapControl.MIPMAP_NONE, usage);
}
+ /**
+ * Creates a renderscript allocation for use by the script with
+ * the size specified by the type and no mipmaps generated by
+ * default
+ *
+ * @param rs
+ * @param type renderscript type describing data layout
+ *
+ * @return allocation
+ */
static public Allocation createTyped(RenderScript rs, Type type) {
return createTyped(rs, type, MipmapControl.MIPMAP_NONE, USAGE_SCRIPT);
}
+ /**
+ * Creates a renderscript allocation with a specified number of
+ * given elements
+ *
+ * @param rs
+ * @param e describes what each element of an allocation is
+ * @param count specifies the number of element in the allocation
+ * @param usage bit field specifying how the allocation is
+ * utilized
+ *
+ * @return allocation
+ */
static public Allocation createSized(RenderScript rs, Element e,
int count, int usage) {
rs.validate();
@@ -513,6 +554,16 @@
return new Allocation(id, rs, t, usage);
}
+ /**
+ * Creates a renderscript allocation with a specified number of
+ * given elements
+ *
+ * @param rs
+ * @param e describes what each element of an allocation is
+ * @param count specifies the number of element in the allocation
+ *
+ * @return allocation
+ */
static public Allocation createSized(RenderScript rs, Element e, int count) {
return createSized(rs, e, count, USAGE_SCRIPT);
}
@@ -544,6 +595,19 @@
return tb.create();
}
+ /**
+ * Creates a renderscript allocation from a bitmap
+ *
+ * @param rs
+ * @param b bitmap source for the allocation data
+ * @param mips specifies desired mipmap behaviour for the
+ * allocation
+ * @param usage bit field specifying how the allocation is
+ * utilized
+ *
+ * @return renderscript allocation containing bitmap data
+ *
+ */
static public Allocation createFromBitmap(RenderScript rs, Bitmap b,
MipmapControl mips,
int usage) {
@@ -557,23 +621,35 @@
return new Allocation(id, rs, t, usage);
}
+ /**
+ * Creates a non-mipmapped renderscript allocation to use as a
+ * graphics texture
+ *
+ * @param rs
+ * @param b bitmap source for the allocation data
+ *
+ * @return renderscript allocation containing bitmap data
+ *
+ */
static public Allocation createFromBitmap(RenderScript rs, Bitmap b) {
return createFromBitmap(rs, b, MipmapControl.MIPMAP_NONE,
USAGE_GRAPHICS_TEXTURE);
}
/**
- * Creates a cubemap allocation from a bitmap containing the
- * horizontal list of cube faces. Each individual face must be
- * the same size and power of 2
- *
- * @param rs
- * @param b bitmap with cubemap faces layed out in the following
- * format: right, left, top, bottom, front, back
- * @param mips specifies desired mipmap behaviour for the cubemap
- * @param usage bitfield specifying how the cubemap is utilized
- *
- **/
+ * Creates a cubemap allocation from a bitmap containing the
+ * horizontal list of cube faces. Each individual face must be
+ * the same size and power of 2
+ *
+ * @param rs
+ * @param b bitmap with cubemap faces layed out in the following
+ * format: right, left, top, bottom, front, back
+ * @param mips specifies desired mipmap behaviour for the cubemap
+ * @param usage bit field specifying how the cubemap is utilized
+ *
+ * @return allocation containing cubemap data
+ *
+ */
static public Allocation createCubemapFromBitmap(RenderScript rs, Bitmap b,
MipmapControl mips,
int usage) {
@@ -608,12 +684,43 @@
return new Allocation(id, rs, t, usage);
}
+ /**
+ * Creates a non-mipmapped cubemap allocation for use as a
+ * graphics texture from a bitmap containing the horizontal list
+ * of cube faces. Each individual face must be the same size and
+ * power of 2
+ *
+ * @param rs
+ * @param b bitmap with cubemap faces layed out in the following
+ * format: right, left, top, bottom, front, back
+ *
+ * @return allocation containing cubemap data
+ *
+ */
static public Allocation createCubemapFromBitmap(RenderScript rs,
Bitmap b) {
return createCubemapFromBitmap(rs, b, MipmapControl.MIPMAP_NONE,
USAGE_GRAPHICS_TEXTURE);
}
+ /**
+ * Creates a cubemap allocation from 6 bitmaps containing
+ * the cube faces. All the faces must be the same size and
+ * power of 2
+ *
+ * @param rs
+ * @param xpos cubemap face in the positive x direction
+ * @param xneg cubemap face in the negative x direction
+ * @param ypos cubemap face in the positive y direction
+ * @param yneg cubemap face in the negative y direction
+ * @param zpos cubemap face in the positive z direction
+ * @param zneg cubemap face in the negative z direction
+ * @param mips specifies desired mipmap behaviour for the cubemap
+ * @param usage bit field specifying how the cubemap is utilized
+ *
+ * @return allocation containing cubemap data
+ *
+ */
static public Allocation createCubemapFromCubeFaces(RenderScript rs,
Bitmap xpos,
Bitmap xneg,
@@ -663,6 +770,23 @@
return cubemap;
}
+ /**
+ * Creates a non-mipmapped cubemap allocation for use as a
+ * graphics texture from 6 bitmaps containing
+ * the cube faces. All the faces must be the same size and
+ * power of 2
+ *
+ * @param rs
+ * @param xpos cubemap face in the positive x direction
+ * @param xneg cubemap face in the negative x direction
+ * @param ypos cubemap face in the positive y direction
+ * @param yneg cubemap face in the negative y direction
+ * @param zpos cubemap face in the positive z direction
+ * @param zneg cubemap face in the negative z direction
+ *
+ * @return allocation containing cubemap data
+ *
+ */
static public Allocation createCubemapFromCubeFaces(RenderScript rs,
Bitmap xpos,
Bitmap xneg,
@@ -675,6 +799,21 @@
USAGE_GRAPHICS_TEXTURE);
}
+ /**
+ * Creates a renderscript allocation from the bitmap referenced
+ * by resource id
+ *
+ * @param rs
+ * @param res application resources
+ * @param id resource id to load the data from
+ * @param mips specifies desired mipmap behaviour for the
+ * allocation
+ * @param usage bit field specifying how the allocation is
+ * utilized
+ *
+ * @return renderscript allocation containing resource data
+ *
+ */
static public Allocation createFromBitmapResource(RenderScript rs,
Resources res,
int id,
@@ -688,6 +827,17 @@
return alloc;
}
+ /**
+ * Creates a non-mipmapped renderscript allocation to use as a
+ * graphics texture from the bitmap referenced by resource id
+ *
+ * @param rs
+ * @param res application resources
+ * @param id resource id to load the data from
+ *
+ * @return renderscript allocation containing resource data
+ *
+ */
static public Allocation createFromBitmapResource(RenderScript rs,
Resources res,
int id) {
@@ -696,6 +846,16 @@
USAGE_GRAPHICS_TEXTURE);
}
+ /**
+ * Creates a renderscript allocation containing string data
+ * encoded in UTF-8 format
+ *
+ * @param rs
+ * @param str string to create the allocation from
+ * @param usage bit field specifying how the allocaiton is
+ * utilized
+ *
+ */
static public Allocation createFromString(RenderScript rs,
String str,
int usage) {
diff --git a/graphics/java/android/renderscript/ProgramStore.java b/graphics/java/android/renderscript/ProgramStore.java
index 0e2227e..d79900e 100644
--- a/graphics/java/android/renderscript/ProgramStore.java
+++ b/graphics/java/android/renderscript/ProgramStore.java
@@ -22,16 +22,61 @@
/**
+ * ProgarmStore 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
*
**/
public class ProgramStore extends BaseObj {
+ /**
+ * Specifies the function used to determine whether a fragment
+ * will be drawn during the depth testing stage in the rendering
+ * pipeline by comparing its value with that already in the depth
+ * buffer. DepthFunc is only valid when depth buffer is present
+ * and depth testing is enabled
+ */
public enum DepthFunc {
+
+ /**
+ * Always drawn
+ */
ALWAYS (0),
+ /**
+ * Drawn if the incoming depth value is less than that in the
+ * depth buffer
+ */
LESS (1),
+ /**
+ * Drawn if the incoming depth value is less or equal to that in
+ * the depth buffer
+ */
LESS_OR_EQUAL (2),
+ /**
+ * Drawn if the incoming depth value is greater than that in the
+ * depth buffer
+ */
GREATER (3),
+ /**
+ * Drawn if the incoming depth value is greater or equal to that
+ * in the depth buffer
+ */
GREATER_OR_EQUAL (4),
+ /**
+ * Drawn if the incoming depth value is equal to that in the
+ * depth buffer
+ */
EQUAL (5),
+ /**
+ * Drawn if the incoming depth value is not equal to that in the
+ * depth buffer
+ */
NOT_EQUAL (6);
int mID;
@@ -40,6 +85,14 @@
}
}
+ /**
+ * Specifies the functions used to combine incoming pixels with
+ * those already in the frame buffer.
+ *
+ * BlendSrcFunc describes how the coefficient used to scale the
+ * source pixels during the blending operation is computed
+ *
+ */
public enum BlendSrcFunc {
ZERO (0),
ONE (1),
@@ -57,6 +110,15 @@
}
}
+ /**
+ * Specifies the functions used to combine incoming pixels with
+ * those already in the frame buffer.
+ *
+ * BlendDstFunc describes how the coefficient used to scale the
+ * pixels already in the framebuffer is computed during the
+ * blending operation
+ *
+ */
public enum BlendDstFunc {
ZERO (0),
ONE (1),
@@ -78,6 +140,17 @@
super(id, rs);
}
+ /**
+ * Returns a pre-defined program store object with the following
+ * characteristics:
+ * - incoming pixels are drawn if their depth value is less than
+ * the stored value in the depth buffer. If the pixel is
+ * drawn, its value is also stored in the depth buffer
+ * - incoming pixels override the value stored in the color
+ * buffer if it passes the depth test
+ *
+ * @param rs
+ **/
public static ProgramStore BLEND_NONE_DEPTH_TEST(RenderScript rs) {
if(rs.mProgramStore_BLEND_NONE_DEPTH_TEST == null) {
ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -89,6 +162,16 @@
}
return rs.mProgramStore_BLEND_NONE_DEPTH_TEST;
}
+ /**
+ * Returns a pre-defined program store object with the following
+ * characteristics:
+ * - incoming pixels always pass the depth test and their value
+ * is not stored in the depth buffer
+ * - incoming pixels override the value stored in the color
+ * buffer
+ *
+ * @param rs
+ **/
public static ProgramStore BLEND_NONE_DEPTH_NONE(RenderScript rs) {
if(rs.mProgramStore_BLEND_NONE_DEPTH_NO_DEPTH == null) {
ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -100,7 +183,19 @@
}
return rs.mProgramStore_BLEND_NONE_DEPTH_NO_DEPTH;
}
-
+ /**
+ * Returns a pre-defined program store object with the following
+ * characteristics:
+ * - incoming pixels are drawn if their depth value is less than
+ * the stored value in the depth buffer. If the pixel is
+ * drawn, its value is also stored in the depth buffer
+ * - if the incoming (Source) pixel passes depth test, its value
+ * is combined with the stored color (Dest) using the
+ * following formula
+ * Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
+ *
+ * @param rs
+ **/
public static ProgramStore BLEND_ALPHA_DEPTH_TEST(RenderScript rs) {
if(rs.mProgramStore_BLEND_ALPHA_DEPTH_TEST == null) {
ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -112,6 +207,17 @@
}
return rs.mProgramStore_BLEND_ALPHA_DEPTH_TEST;
}
+ /**
+ * Returns a pre-defined program store object with the following
+ * characteristics:
+ * - incoming pixels always pass the depth test and their value
+ * is not stored in the depth buffer
+ * - incoming pixel's value is combined with the stored color
+ * (Dest) using the following formula
+ * Final.RGB = Source.RGB * Source.A + Dest.RGB * (1 - Source.A)
+ *
+ * @param rs
+ **/
public static ProgramStore BLEND_ALPHA_DEPTH_NONE(RenderScript rs) {
if(rs.mProgramStore_BLEND_ALPHA_DEPTH_NO_DEPTH == null) {
ProgramStore.Builder builder = new ProgramStore.Builder(rs);
@@ -124,6 +230,11 @@
return rs.mProgramStore_BLEND_ALPHA_DEPTH_NO_DEPTH;
}
+ /**
+ * Builder class for ProgramStore object. If the builder is left
+ * empty, the equivalent of BLEND_NONE_DEPTH_NONE would be
+ * returned
+ */
public static class Builder {
RenderScript mRS;
DepthFunc mDepthFunc;
@@ -148,16 +259,41 @@
mBlendDst = BlendDstFunc.ZERO;
}
+ /**
+ * Specifies the depth testing behavior
+ *
+ * @param func function used for depth testing
+ *
+ * @return this
+ */
public Builder setDepthFunc(DepthFunc func) {
mDepthFunc = func;
return this;
}
+ /**
+ * Enables writes into the depth buffer
+ *
+ * @param enable specifies whether depth writes are
+ * enabled or disabled
+ *
+ * @return this
+ */
public Builder setDepthMaskEnabled(boolean enable) {
mDepthMask = enable;
return this;
}
+ /**
+ * Enables writes into the color buffer
+ *
+ * @param r specifies whether red channel is written
+ * @param g specifies whether green channel is written
+ * @param b specifies whether blue channel is written
+ * @param a specifies whether alpha channel is written
+ *
+ * @return this
+ */
public Builder setColorMaskEnabled(boolean r, boolean g, boolean b, boolean a) {
mColorMaskR = r;
mColorMaskG = g;
@@ -166,12 +302,31 @@
return this;
}
+ /**
+ * Specifies how incoming pixels are combined with the pixels
+ * stored in the framebuffer
+ *
+ * @param src specifies how the source blending factor is
+ * computed
+ * @param dst specifies how the destination blending factor is
+ * computed
+ *
+ * @return this
+ */
public Builder setBlendFunc(BlendSrcFunc src, BlendDstFunc dst) {
mBlendSrc = src;
mBlendDst = dst;
return this;
}
+ /**
+ * Enables dithering
+ *
+ * @param enable specifies whether dithering is enabled or
+ * disabled
+ *
+ * @return this
+ */
public Builder setDitherEnabled(boolean enable) {
mDither = enable;
return this;
@@ -192,6 +347,9 @@
return new ProgramStore(id, rs);
}
+ /**
+ * Creates a program store from the current state of the builder
+ */
public ProgramStore create() {
mRS.validate();
return internalCreate(mRS, this);