Document RS element and type and add validity checking to type creation. (a1b13ed0) · Commits · e / os / android_frameworks_base

graphics/java/android/renderscript/Element.java

+128 −1

Original line number	Diff line number	Diff line
		@@ -22,6 +22,25 @@ import android.util.Log;
		/**
		* @hide
		*
		* Element is the basic data type of RenderScript. An element can be of 2
		* forms. Basic elements contain a single component of data. This can be of
		* any of the legal RS types. Examples of basic element types.
		* Single float value
		* 4 element float vector
		* single RGB-565 color
		* single unsigned int 16
		*
		* Complex elements will contain a list of sub-elements and names. This in
		* effect represents a structure of data. The fields can be accessed by name
		* from a script or shader. The memory layout is defined and ordered. Data
		* alignment is determinied by the most basic primitive type. i.e. a float4
		* vector will be alligned to sizeof(float) and not sizeof(float4). The
		* ordering of elements in memory will be the order in which they were added
		* with each component aligned as necessary. No re-ordering will be done.
		*
		* The primary source of elements will be from scripts. A script that exports a
		* bind point for a data structure will generate a RS element to represent the
		* data exported by the script.
		**/
		public class Element extends BaseObj {
		int mSize;
		@@ -36,6 +55,21 @@ public class Element extends BaseObj {

		int getSizeBytes() {return mSize;}


		/**
		* DataType represents the basic type information for a basic element. The
		* naming convention follows. For numeric types its FLOAT, SIGNED, UNSIGNED
		* followed by the _BITS where BITS is the size of the data. BOOLEAN is a
		* true / false (1,0) represented in an 8 bit container. The UNSIGNED
		* variants with multiple bit definitions are for packed graphical data
		* formats and represents vectors with per vector member sizes which are
		* treated as a single unit for packing and alignment purposes.
		*
		* MATRIX the three matrix types contain FLOAT_32 elements and are treated
		* as 32 bits for alignment purposes.
		*
		* RS_* objects. 32 bit opaque handles.
		*/
		public enum DataType {
		//FLOAT_16 (1, 2),
		FLOAT_32 (2, 4),
		@@ -78,6 +112,12 @@ public class Element extends BaseObj {
		}
		}

		/**
		* The special interpretation of the data if required. This is primarly
		* useful for graphical data. USER indicates no special interpretation is
		* expected. PIXEL is used in conjunction with the standard data types for
		* representing texture formats.
		*/
		public enum DataKind {
		USER (0),

		@@ -93,6 +133,12 @@ public class Element extends BaseObj {
		}
		}

		/**
		* Return if a element is too complex for use as a data source for a Mesh or
		* a Program.
		*
		* @return boolean
		*/
		public boolean isComplex() {
		if (mElements == null) {
		return false;
		@@ -105,6 +151,13 @@ public class Element extends BaseObj {
		return false;
		}

		/**
		* Utility function for returning an Element containing a single Boolean.
		*
		* @param rs Context to which the element will belong.
		*
		* @return Element
		*/
		public static Element BOOLEAN(RenderScript rs) {
		if(rs.mElement_BOOLEAN == null) {
		rs.mElement_BOOLEAN = createUser(rs, DataType.BOOLEAN);
		@@ -112,6 +165,13 @@ public class Element extends BaseObj {
		return rs.mElement_BOOLEAN;
		}

		/**
		* Utility function for returning an Element containing a single UNSIGNED_8.
		*
		* @param rs Context to which the element will belong.
		*
		* @return Element
		*/
		public static Element U8(RenderScript rs) {
		if(rs.mElement_U8 == null) {
		rs.mElement_U8 = createUser(rs, DataType.UNSIGNED_8);
		@@ -119,6 +179,13 @@ public class Element extends BaseObj {
		return rs.mElement_U8;
		}

		/**
		* Utility function for returning an Element containing a single SIGNED_8.
		*
		* @param rs Context to which the element will belong.
		*
		* @return Element
		*/
		public static Element I8(RenderScript rs) {
		if(rs.mElement_I8 == null) {
		rs.mElement_I8 = createUser(rs, DataType.SIGNED_8);
		@@ -414,7 +481,14 @@ public class Element extends BaseObj {
		super.destroy();
		}

		/////////////////////////////////////////
		/**
		* Create a custom Element of the specified DataType. The DataKind will be
		* set to USER and the vector size to 1 indicating non-vector.
		*
		* @param rs The context associated with the new Element.
		* @param dt The DataType for the new element.
		* @return Element
		*/
		public static Element createUser(RenderScript rs, DataType dt) {
		DataKind dk = DataKind.USER;
		boolean norm = false;
		@@ -423,6 +497,17 @@ public class Element extends BaseObj {
		return new Element(id, rs, dt, dk, norm, vecSize);
		}

		/**
		* Create a custom vector element of the specified DataType and vector size.
		* DataKind will be set to USER.
		*
		* @param rs The context associated with the new Element.
		* @param dt The DataType for the new element.
		* @param size Vector size for the new Element. Range 2-4 inclusive
		* supported.
		*
		* @return Element
		*/
		public static Element createVector(RenderScript rs, DataType dt, int size) {
		if (size < 2 \|\| size > 4) {
		throw new RSIllegalArgumentException("Vector size out of rance 2-4.");
		@@ -433,6 +518,18 @@ public class Element extends BaseObj {
		return new Element(id, rs, dt, dk, norm, size);
		}

		/**
		* Create a new pixel Element type. A matching DataType and DataKind must
		* be provided. The DataType and DataKind must contain the same number of
		* components. Vector size will be set to 1.
		*
		* @param rs The context associated with the new Element.
		* @param dt The DataType for the new element.
		* @param dk The DataKind to specify the mapping of each component in the
		* DataType.
		*
		* @return Element
		*/
		public static Element createPixel(RenderScript rs, DataType dt, DataKind dk) {
		if (!(dk == DataKind.PIXEL_L \|\|
		dk == DataKind.PIXEL_A \|\|
		@@ -473,6 +570,12 @@ public class Element extends BaseObj {
		return new Element(id, rs, dt, dk, norm, size);
		}

		/**
		* Builder class for producing complex elements with matching field and name
		* pairs. The builder starts empty. The order in which elements are added
		* is retained for the layout in memory.
		*
		*/
		public static class Builder {
		RenderScript mRS;
		Element[] mElements;
		@@ -480,6 +583,11 @@ public class Element extends BaseObj {
		int[] mArraySizes;
		int mCount;

		/**
		* Create a builder object.
		*
		* @param rs
		*/
		public Builder(RenderScript rs) {
		mRS = rs;
		mCount = 0;
		@@ -488,6 +596,13 @@ public class Element extends BaseObj {
		mArraySizes = new int[8];
		}

		/**
		* Add an array of elements to this element.
		*
		* @param element
		* @param name
		* @param arraySize
		*/
		public void add(Element element, String name, int arraySize) {
		if (arraySize < 1) {
		throw new RSIllegalArgumentException("Array size cannot be less than 1.");
		@@ -509,10 +624,22 @@ public class Element extends BaseObj {
		mCount++;
		}

		/**
		* Add a single element to this Element.
		*
		* @param element
		* @param name
		*/
		public void add(Element element, String name) {
		add(element, name, 1);
		}

		/**
		* Create the element from this builder.
		*
		*
		* @return Element
		*/
		public Element create() {
		mRS.validate();
		Element[] ein = new Element[mCount];

graphics/java/android/renderscript/Type.java

+96 −0

Original line number	Diff line number	Diff line
		@@ -23,6 +23,20 @@ import android.util.Log;
		/**
		* @hide
		*
		* Type is an allocation template. It consists of an Element and one or more
		* dimensions. It describes only the layout of memory but does not allocate and
		* storage for the data thus described.
		*
		* A Type consists of several dimensions. Those are X, Y, Z, LOD (level of
		* detail), Faces (faces of a cube map). The X,Y,Z dimensions can be assigned
		* any positive integral value within the constraints of available memory. A
		* single dimension allocation would have an X dimension of greater than zero
		* while the Y and Z dimensions would be zero to indicate not present. In this
		* regard an allocation of x=10, y=1 would be considered 2 dimensionsal while
		* x=10, y=0 would be considered 1 dimensional.
		*
		* The LOD and Faces dimensions are booleans to indicate present or not present.
		*
		**/
		public class Type extends BaseObj {
		int mDimX;
		@@ -33,25 +47,65 @@ public class Type extends BaseObj {
		int mElementCount;
		Element mElement;

		/**
		* Return the element associated with this Type.
		*
		* @return Element
		*/
		public Element getElement() {
		return mElement;
		}

		/**
		* Return the value of the X dimension.
		*
		* @return int
		*/
		public int getX() {
		return mDimX;
		}

		/**
		* Return the value of the Y dimension or 0 for a 1D allocation.
		*
		* @return int
		*/
		public int getY() {
		return mDimY;
		}

		/**
		* Return the value of the Z dimension or 0 for a 1D or 2D allocation.
		*
		* @return int
		*/
		public int getZ() {
		return mDimZ;
		}

		/**
		* Return if the Type has a mipmap chain.
		*
		* @return boolean
		*/
		public boolean getLOD() {
		return mDimLOD;
		}

		/**
		* Return if the Type is a cube map.
		*
		* @return boolean
		*/
		public boolean getFaces() {
		return mDimFaces;
		}

		/**
		* Return the total number of accessable cells in the Type.
		*
		* @return int
		*/
		public int getElementCount() {
		return mElementCount;
		}
		@@ -122,6 +176,10 @@ public class Type extends BaseObj {
		calcElementCount();
		}

		/**
		* Builder class for Type.
		*
		*/
		public static class Builder {
		RenderScript mRS;
		Dimension[] mDimensions;
		@@ -134,6 +192,12 @@ public class Type extends BaseObj {
		int mValue;
		}

		/**
		* Create a new builder object.
		*
		* @param rs
		* @param e The element for the type to be created.
		*/
		public Builder(RenderScript rs, Element e) {
		if(e.getID() == 0) {
		throw new RSIllegalArgumentException("Invalid element.");
		@@ -145,6 +209,13 @@ public class Type extends BaseObj {
		mElement = e;
		}

		/**
		* Add a dimension to the Type.
		*
		*
		* @param d
		* @param value
		*/
		public void add(Dimension d, int value) {
		if(value < 1) {
		throw new RSIllegalArgumentException("Values of less than 1 for Dimensions are not valid.");
		@@ -163,6 +234,11 @@ public class Type extends BaseObj {
		mEntryCount++;
		}

		/**
		* Validate structure and create a new type.
		*
		* @return Type
		*/
		public Type create() {
		int dims[] = new int[mEntryCount];
		for (int ct=0; ct < mEntryCount; ct++) {
		@@ -190,6 +266,26 @@ public class Type extends BaseObj {
		t.mDimFaces = mDimensionValues[ct] != 0;
		}
		}

		if (t.mDimZ > 0) {
		if ((t.mDimX < 1) \|\| (t.mDimY < 1)) {
		throw new RSInvalidStateException("Both X and Y dimension required when Z is present.");
		}
		if (t.mDimFaces) {
		throw new RSInvalidStateException("Cube maps not supported with 3D types.");
		}
		}
		if (t.mDimY > 0) {
		if (t.mDimX < 1) {
		throw new RSInvalidStateException("X dimension required when Y is present.");
		}
		}
		if (t.mDimFaces) {
		if (t.mDimY < 1) {
		throw new RSInvalidStateException("Cube maps require 2D Types.");
		}
		}

		t.calcElementCount();
		return t;
		}