diff options
Diffstat (limited to 'graphics')
6 files changed, 466 insertions, 1 deletions
diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java index 59e3dd9..b77fe7d 100644 --- a/graphics/java/android/renderscript/Mesh.java +++ b/graphics/java/android/renderscript/Mesh.java @@ -23,10 +23,29 @@ import android.util.Log; /** * @hide + * Mesh class is a container for geometric data displayed in + * renderscript. + * + * Internally, mesh is a collection of allocations that + * represent vertex data (positions, normals, texture + * coordinates) and index data such as triangles and lines. + * + * Vertex data could either be interlieved within one + * allocation, provided separately as multiple allocation + * objects or done as a combination of the above. When a + * vertex channel name matches an input in the vertex program, + * renderscript will automatically connect the two together. + * + * Parts of the mesh could be rendered with either explicit + * index sets or primitive types. * **/ public class Mesh extends BaseObj { + /** + * Describes the way mesh vertex data is interpreted when rendering + * + **/ public enum Primitive { POINT (0), LINE (1), @@ -49,25 +68,50 @@ public class Mesh extends BaseObj { super(id, rs); } + /** + * @return number of allocations containing vertex data + * + **/ public int getVertexAllocationCount() { if(mVertexBuffers == null) { return 0; } return mVertexBuffers.length; } + /** + * @param slot index in the list of allocations to return + * @return vertex data allocation at the given index + * + **/ public Allocation getVertexAllocation(int slot) { return mVertexBuffers[slot]; } + /** + * @return number of primitives or index sets in the mesh + * + **/ public int getPrimitiveCount() { if(mIndexBuffers == null) { return 0; } return mIndexBuffers.length; } + + /** + * @param slot locaton within the list of index set allocation + * @return allocation containing primtive index data or null if + * the index data is not specified explicitly + * + **/ public Allocation getIndexSetAllocation(int slot) { return mIndexBuffers[slot]; } + /** + * @param slot locaiton within the list of index set primitives + * @return index set primitive type + * + **/ public Primitive getPrimitive(int slot) { return mPrimitives[slot]; } @@ -105,6 +149,12 @@ public class Mesh extends BaseObj { } } + /** + * Mesh builder object. It starts empty and requires the user to + * add the types necessary to create vertex and index + * allocations + * + */ public static class Builder { RenderScript mRS; int mUsage; @@ -121,6 +171,13 @@ public class Mesh extends BaseObj { Entry[] mVertexTypes; Vector mIndexTypes; + /** + * Creates builder object + * @param rs + * @param usage specifies how the mesh allocations are to be + * handled, whether they need to be uploaded to a + * buffer on the gpu, maintain a cpu copy, etc + */ public Builder(RenderScript rs, int usage) { mRS = rs; mUsage = usage; @@ -129,14 +186,29 @@ public class Mesh extends BaseObj { mIndexTypes = new Vector(); } + /** + * @return internal index of the last vertex buffer type added to + * builder + **/ public int getCurrentVertexTypeIndex() { return mVertexTypeCount - 1; } + /** + * @return internal index of the last index set added to the + * builder + **/ public int getCurrentIndexSetIndex() { return mIndexTypes.size() - 1; } + /** + * Adds a vertex data type to the builder object + * + * @param r type of the vertex data allocation to be created + * + * @return this + **/ public Builder addVertexType(Type t) throws IllegalStateException { if (mVertexTypeCount >= mVertexTypes.length) { throw new IllegalStateException("Max vertex types exceeded."); @@ -149,6 +221,14 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds a vertex data type to the builder object + * + * @param e element describing the vertex data layout + * @param size number of elements in the buffer + * + * @return this + **/ public Builder addVertexType(Element e, int size) throws IllegalStateException { if (mVertexTypeCount >= mVertexTypes.length) { throw new IllegalStateException("Max vertex types exceeded."); @@ -162,6 +242,14 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds an index set data type to the builder object + * + * @param t type of the index set data, could be null + * @param p primitive type + * + * @return this + **/ public Builder addIndexSetType(Type t, Primitive p) { Entry indexType = new Entry(); indexType.t = t; @@ -172,6 +260,13 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds an index set primitive type to the builder object + * + * @param p primitive type + * + * @return this + **/ public Builder addIndexSetType(Primitive p) { Entry indexType = new Entry(); indexType.t = null; @@ -182,6 +277,15 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds an index set data type to the builder object + * + * @param e element describing the index set data layout + * @param size number of elements in the buffer + * @param p primitive type + * + * @return this + **/ public Builder addIndexSetType(Element e, int size, Primitive p) { Entry indexType = new Entry(); indexType.t = null; @@ -237,6 +341,10 @@ public class Mesh extends BaseObj { return newMesh; } + /** + * Create a Mesh object from the current state of the builder + * + **/ public Mesh create() { mRS.validate(); Mesh sm = internalCreate(mRS, this); @@ -244,6 +352,12 @@ public class Mesh extends BaseObj { } } + /** + * Mesh builder object. It starts empty and requires the user to + * add all the vertex and index allocations that comprise the + * mesh + * + */ public static class AllocationBuilder { RenderScript mRS; @@ -264,14 +378,30 @@ public class Mesh extends BaseObj { mIndexTypes = new Vector(); } + /** + * @return internal index of the last vertex buffer type added to + * builder + **/ public int getCurrentVertexTypeIndex() { return mVertexTypeCount - 1; } + /** + * @return internal index of the last index set added to the + * builder + **/ public int getCurrentIndexSetIndex() { return mIndexTypes.size() - 1; } + /** + * Adds an allocation containing vertex buffer data to the + * builder + * + * @param a vertex data allocation + * + * @return this + **/ public AllocationBuilder addVertexAllocation(Allocation a) throws IllegalStateException { if (mVertexTypeCount >= mVertexTypes.length) { throw new IllegalStateException("Max vertex types exceeded."); @@ -283,6 +413,15 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds an allocation containing index buffer data and index type + * to the builder + * + * @param a index set data allocation, could be null + * @param p index set primitive type + * + * @return this + **/ public AllocationBuilder addIndexSetAllocation(Allocation a, Primitive p) { Entry indexType = new Entry(); indexType.a = a; @@ -291,6 +430,13 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds an index set type to the builder + * + * @param p index set primitive type + * + * @return this + **/ public AllocationBuilder addIndexSetType(Primitive p) { Entry indexType = new Entry(); indexType.a = null; @@ -325,6 +471,10 @@ public class Mesh extends BaseObj { return newMesh; } + /** + * Create a Mesh object from the current state of the builder + * + **/ public Mesh create() { mRS.validate(); Mesh sm = internalCreate(mRS, this); @@ -332,7 +482,11 @@ public class Mesh extends BaseObj { } } - + /** + * Builder that allows creation of a mesh object point by point + * and triangle by triangle + * + **/ public static class TriangleMeshBuilder { float mVtxData[]; int mVtxCount; @@ -358,6 +512,15 @@ public class Mesh extends BaseObj { public static final int NORMAL = 0x0002; public static final int TEXTURE_0 = 0x0100; + /** + * @param rs + * @param vtxSize specifies whether the vertex is a float2 or + * float3 + * @param flags bitfield that is a combination of COLOR, NORMAL, + * and TEXTURE_0 that specifies what vertex data + * channels are present in the mesh + * + **/ public TriangleMeshBuilder(RenderScript rs, int vtxSize, int flags) { mRS = rs; mVtxCount = 0; @@ -401,6 +564,15 @@ public class Mesh extends BaseObj { } } + /** + * Adds a float2 vertex to the mesh + * + * @param x position x + * @param y position y + * + * @return this + * + **/ public TriangleMeshBuilder addVertex(float x, float y) { if (mVtxSize != 2) { throw new IllegalStateException("add mistmatch with declared components."); @@ -412,6 +584,16 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds a float3 vertex to the mesh + * + * @param x position x + * @param y position y + * @param z position z + * + * @return this + * + **/ public TriangleMeshBuilder addVertex(float x, float y, float z) { if (mVtxSize != 3) { throw new IllegalStateException("add mistmatch with declared components."); @@ -424,6 +606,14 @@ public class Mesh extends BaseObj { return this; } + /** + * Sets the texture coordinate for the last added vertex + * + * @param s texture coordinate s + * @param t texture coordinate t + * + * @return this + **/ public TriangleMeshBuilder setTexture(float s, float t) { if ((mFlags & TEXTURE_0) == 0) { throw new IllegalStateException("add mistmatch with declared components."); @@ -433,6 +623,15 @@ public class Mesh extends BaseObj { return this; } + /** + * Sets the normal vector for the last added vertex + * + * @param x normal vector x + * @param y normal vector y + * @param z normal vector z + * + * @return this + **/ public TriangleMeshBuilder setNormal(float x, float y, float z) { if ((mFlags & NORMAL) == 0) { throw new IllegalStateException("add mistmatch with declared components."); @@ -443,6 +642,16 @@ public class Mesh extends BaseObj { return this; } + /** + * Sets the color for the last added vertex + * + * @param r red component + * @param g green component + * @param b blue component + * @param a alpha component + * + * @return this + **/ public TriangleMeshBuilder setColor(float r, float g, float b, float a) { if ((mFlags & COLOR) == 0) { throw new IllegalStateException("add mistmatch with declared components."); @@ -454,6 +663,15 @@ public class Mesh extends BaseObj { return this; } + /** + * Adds a new triangle to the mesh builder + * + * @param idx1 index of the first vertex in the triangle + * @param idx2 index of the second vertex in the triangle + * @param idx3 index of the third vertex in the triangle + * + * @return this + **/ public TriangleMeshBuilder addTriangle(int idx1, int idx2, int idx3) { if((idx1 >= mVtxCount) || (idx1 < 0) || (idx2 >= mVtxCount) || (idx2 < 0) || @@ -471,6 +689,20 @@ public class Mesh extends BaseObj { return this; } + /** + * Creates the mesh object from the current state of the builder + * + * @param uploadToBufferObject specifies whether the vertex data + * is to be uploaded into the buffer + * object indicating that it's likely + * not going to be modified and + * rendered many times. + * Alternatively, it indicates the + * mesh data will be updated + * frequently and remain in script + * accessible memory + * + **/ public Mesh create(boolean uploadToBufferObject) { Element.Builder b = new Element.Builder(mRS); int floatCount = mVtxSize; diff --git a/graphics/java/android/renderscript/Program.java b/graphics/java/android/renderscript/Program.java index b07ae7d..fdd138c 100644 --- a/graphics/java/android/renderscript/Program.java +++ b/graphics/java/android/renderscript/Program.java @@ -28,6 +28,9 @@ import android.util.Log; /** * + * Program is a base class for all the objects that modify + * various stages of the graphics pipeline + * **/ public class Program extends BaseObj { public static final int MAX_INPUT = 8; @@ -35,6 +38,12 @@ public class Program extends BaseObj { public static final int MAX_CONSTANT = 8; public static final int MAX_TEXTURE = 8; + /** + * + * TextureType specifies what textures are attached to Program + * objects + * + **/ public enum TextureType { TEXTURE_2D (0), TEXTURE_CUBE (1); @@ -68,6 +77,14 @@ public class Program extends BaseObj { super(id, rs); } + /** + * Binds a constant buffer to be used as uniform inputs to the + * program + * + * @param a allocation containing uniform data + * @param slot index within the program's list of constant + * buffer allocations + */ public void bindConstants(Allocation a, int slot) { if (slot < 0 || slot >= mConstants.length) { throw new IllegalArgumentException("Slot ID out of range."); @@ -80,6 +97,13 @@ public class Program extends BaseObj { mRS.nProgramBindConstants(getID(), slot, id); } + /** + * Binds a texture to be used in the program + * + * @param va allocation containing texture data + * @param slot index within the program's list of textures + * + */ public void bindTexture(Allocation va, int slot) throws IllegalArgumentException { mRS.validate(); @@ -95,6 +119,15 @@ public class Program extends BaseObj { mRS.nProgramBindTexture(getID(), slot, id); } + /** + * Binds an object that describes how a texture at the + * corresponding location is sampled + * + * @param vs sampler for a corresponding texture + * @param slot index within the program's list of textures to + * use the sampler on + * + */ public void bindSampler(Sampler vs, int slot) throws IllegalArgumentException { mRS.validate(); @@ -133,11 +166,25 @@ public class Program extends BaseObj { mTextureTypes = new TextureType[MAX_TEXTURE]; } + /** + * Sets the GLSL shader code to be used in the program + * + * @param s GLSL shader string + * @return self + */ public BaseProgramBuilder setShader(String s) { mShader = s; return this; } + /** + * Sets the GLSL shader code to be used in the program + * + * @param resources application resources + * @param resourceID id of the file containing GLSL shader code + * + * @return self + */ public BaseProgramBuilder setShader(Resources resources, int resourceID) { byte[] str; int strLength; @@ -176,14 +223,29 @@ public class Program extends BaseObj { return this; } + /** + * Queries the index of the last added constant buffer type + * + */ public int getCurrentConstantIndex() { return mConstantCount - 1; } + /** + * Queries the index of the last added texture type + * + */ public int getCurrentTextureIndex() { return mTextureCount - 1; } + /** + * Adds constant (uniform) inputs to the program + * + * @param t Type that describes the layout of the Allocation + * object to be used as constant inputs to the Program + * @return self + */ public BaseProgramBuilder addConstant(Type t) throws IllegalStateException { // Should check for consistant and non-conflicting names... if(mConstantCount >= MAX_CONSTANT) { @@ -197,6 +259,13 @@ public class Program extends BaseObj { return this; } + /** + * Adds a texture input to the Program + * + * @param texType describes that the texture to append it (2D, + * Cubemap, etc.) + * @return self + */ public BaseProgramBuilder addTexture(TextureType texType) throws IllegalArgumentException { if(mTextureCount >= MAX_TEXTURE) { throw new IllegalArgumentException("Max texture count exceeded."); diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java index 7f12661..14c0c01 100644 --- a/graphics/java/android/renderscript/ProgramFragment.java +++ b/graphics/java/android/renderscript/ProgramFragment.java @@ -22,6 +22,9 @@ import android.util.Log; /** + * ProgramFragment, also know as a fragment shader, describes a + * stage in the graphics pipeline responsible for manipulating + * pixel data in a user-defined way. * **/ public class ProgramFragment extends Program { @@ -30,10 +33,20 @@ public class ProgramFragment extends Program { } public static class Builder extends BaseProgramBuilder { + /** + * Create a builder object. + * + * @param rs + */ public Builder(RenderScript rs) { super(rs); } + /** + * Creates ProgramFragment from the current state of the builder + * + * @return ProgramFragment + */ public ProgramFragment create() { mRS.validate(); int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2]; diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java index f0040c6..663bc9f 100644 --- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java +++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java @@ -22,6 +22,13 @@ import android.util.Log; /** + * ProgramFragmentFixedFunction is a helper class that provides + * a way to make a simple fragment shader without writing any + * GLSL code. + * + * This class allows for display of constant color, interpolated + * color from vertex shader, or combinations of the above + * blended with results of up to two texture lookups. * **/ public class ProgramFragmentFixedFunction extends ProgramFragment { @@ -34,6 +41,12 @@ public class ProgramFragmentFixedFunction extends ProgramFragment { super(rs); } + /** + * Creates ProgramFragmentFixedFunction from the current state + * of the builder + * + * @return ProgramFragmentFixedFunction + */ public ProgramFragmentFixedFunction create() { mRS.validate(); int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2]; @@ -71,6 +84,11 @@ public class ProgramFragmentFixedFunction extends ProgramFragment { String mShader; RenderScript mRS; + /** + * EnvMode describes how textures are combined with the existing + * color in the fixed function fragment shader + * + **/ public enum EnvMode { REPLACE (1), MODULATE (2), @@ -82,6 +100,11 @@ public class ProgramFragmentFixedFunction extends ProgramFragment { } } + /** + * Format describes the pixel format of textures in the fixed + * function fragment shader and how they are sampled + * + **/ public enum Format { ALPHA (1), LUMINANCE_ALPHA (2), @@ -168,12 +191,30 @@ public class ProgramFragmentFixedFunction extends ProgramFragment { mShader += "}\n"; } + /** + * Creates a builder for fixed function fragment program + * + * @param rs + */ public Builder(RenderScript rs) { mRS = rs; mSlots = new Slot[MAX_TEXTURE]; mPointSpriteEnable = false; } + /** + * Adds a texture to be fetched as part of the fixed function + * fragment program + * + * @param env specifies how the texture is combined with the + * current color + * @param fmt specifies the format of the texture and how its + * components will be used to combine with the + * current color + * @param slot index of the texture to apply the operations on + * + * @return this + */ public Builder setTexture(EnvMode env, Format fmt, int slot) throws IllegalArgumentException { if((slot < 0) || (slot >= MAX_TEXTURE)) { @@ -183,16 +224,34 @@ public class ProgramFragmentFixedFunction extends ProgramFragment { return this; } + /** + * Specifies whether the texture coordinate passed from the + * vertex program is replaced with an openGL internal point + * sprite texture coordinate + * + **/ public Builder setPointSpriteTexCoordinateReplacement(boolean enable) { mPointSpriteEnable = enable; return this; } + /** + * Specifies whether the varying color passed from the vertex + * program or the constant color set on the fragment program is + * used in the final color calculation in the fixed function + * fragment shader + * + **/ public Builder setVaryingColor(boolean enable) { mVaryingColorEnable = enable; return this; } + /** + * Creates the fixed function fragment program from the current + * state of the builder. + * + */ public ProgramFragmentFixedFunction create() { InternalBuilder sb = new InternalBuilder(mRS); mNumTextures = 0; diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java index 13800ff..7ba8b82 100644 --- a/graphics/java/android/renderscript/ProgramVertex.java +++ b/graphics/java/android/renderscript/ProgramVertex.java @@ -23,6 +23,9 @@ import android.util.Log; /** + * ProgramVertex, also know as a vertex shader, describes a + * stage in the graphics pipeline responsible for manipulating + * geometric data in a user-defined way. * **/ public class ProgramVertex extends Program { @@ -31,11 +34,31 @@ public class ProgramVertex extends Program { super(id, rs); } + /** + * 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 { + /** + * Create a builder object. + * + * @param rs + */ public Builder(RenderScript rs) { super(rs); } + /** + * Add varying inputs to the program + * + * @param e element describing the layout of the varying input + * structure + * @return self + */ public Builder addInput(Element e) throws IllegalStateException { // Should check for consistant and non-conflicting names... if(mInputCount >= MAX_INPUT) { @@ -48,6 +71,11 @@ public class ProgramVertex extends Program { return this; } + /** + * Creates ProgramVertex from the current state of the builder + * + * @return ProgramVertex + */ public ProgramVertex create() { mRS.validate(); int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2]; diff --git a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java index 1b69efe..b9537c7 100644 --- a/graphics/java/android/renderscript/ProgramVertexFixedFunction.java +++ b/graphics/java/android/renderscript/ProgramVertexFixedFunction.java @@ -23,6 +23,9 @@ import android.util.Log; /** + * ProgramVertexFixedFunction is a helper class that provides a + * simple way to create a fixed function emulation vertex shader + * without writing any GLSL code. * **/ public class ProgramVertexFixedFunction extends ProgramVertex { @@ -31,6 +34,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex { super(id, rs); } + /** + * Binds the constant buffer containing fixed function emulation + * matrices + * + * @param va allocation containing fixed function matrices + */ public void bindConstants(Constants va) { mRS.validate(); bindConstants(va.getAllocation(), 0); @@ -53,6 +62,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex { return this; } + /** + * Creates ProgramVertexFixedFunction from the current state of + * the builder + * + * @return ProgramVertexFixedFunction + */ public ProgramVertexFixedFunction create() { mRS.validate(); int[] tmp = new int[(mInputCount + mOutputCount + mConstantCount + mTextureCount) * 2]; @@ -87,10 +102,20 @@ public class ProgramVertexFixedFunction extends ProgramVertex { String mShader; RenderScript mRS; + /** + * Creates a builder for fixed function vertex program + * + * @param rs + */ public Builder(RenderScript rs) { mRS = rs; } + /** + * Specifies whether texture matrix calculations are to be added + * to the shader + * + */ public Builder setTextureMatrixEnable(boolean enable) { mTextureMatrixEnable = enable; return this; @@ -126,6 +151,12 @@ public class ProgramVertexFixedFunction extends ProgramVertex { mShader += "}\n"; } + /** + * Creates ProgramVertexFixedFunction from the current state of + * the builder + * + * @return Fixed function emulation ProgramVertex + */ public ProgramVertexFixedFunction create() { buildShaderString(); @@ -144,6 +175,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex { } } + /** + * Helper class to store modelview, projection and texture + * matrices for ProgramVertexFixedFunction + * + */ public static class Constants { static final int MODELVIEW_OFFSET = 0; static final int PROJECTION_OFFSET = 16; @@ -159,6 +195,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex { } private FieldPacker mIOBuffer; + /** + * Creates buffer to store fixed function emulation matrices + * + * @param rs + **/ public Constants(RenderScript rs) { Type constInputType = ProgramVertexFixedFunction.Builder.getConstantInputType(rs); mAlloc = Allocation.createTyped(rs, constInputType); @@ -173,6 +214,11 @@ public class ProgramVertexFixedFunction extends ProgramVertex { setTexture(new Matrix4f()); } + /** + * Forces deallocation of memory backing the contant matrices. + * Normally, this is unnecessary and will be garbage collected + * + */ public void destroy() { mAlloc.destroy(); mAlloc = null; @@ -186,16 +232,34 @@ public class ProgramVertexFixedFunction extends ProgramVertex { mAlloc.copyFrom(mIOBuffer.getData()); } + /** + * Sets the modelview matrix in the fixed function matrix buffer + * + * @param m modelview matrix + */ public void setModelview(Matrix4f m) { mModel.load(m); addToBuffer(MODELVIEW_OFFSET*4, m); } + /** + * Sets the projection matrix in the fixed function matrix buffer + * + * @param m projection matrix + */ public void setProjection(Matrix4f m) { mProjection.load(m); addToBuffer(PROJECTION_OFFSET*4, m); } + /** + * Sets the texture matrix in the fixed function matrix buffer. + * Texture matrix must be enabled in the + * ProgramVertexFixedFunction builder for the shader to utilize + * it. + * + * @param m modelview matrix + */ public void setTexture(Matrix4f m) { mTexture.load(m); addToBuffer(TEXTURE_OFFSET*4, m); |