Merge "Updated Mesh documentation" (839681b8) · Commits · e / os / android_frameworks_base

graphics/java/android/graphics/Mesh.java

+63 −20

Original line number	Diff line number	Diff line
		@@ -29,7 +29,8 @@ import java.nio.ShortBuffer;
		* {@link #makeIndexed(MeshSpecification, Mode, Buffer, int, ShortBuffer, Rect)} methods,
		* where a {@link MeshSpecification} is required along with various attributes for
		* detailing the mesh object, including a mode, vertex buffer, optional index buffer, and bounds
		* for the mesh.
		* for the mesh. Once generated, a mesh object can be drawn through
		* {@link Canvas#drawMesh(Mesh, BlendMode, Paint)}
		*
		* @hide
		*/
		@@ -53,8 +54,12 @@ public class Mesh {
		*
		* @param meshSpec {@link MeshSpecification} used when generating the mesh.
		* @param mode {@link Mode} enum
		* @param vertexBuffer vertex buffer representing through {@link Buffer}.
		* @param vertexCount the number of vertices represented in the vertexBuffer.
		* @param vertexBuffer vertex buffer representing through {@link Buffer}. This provides the data
		* for all attributes provided within the meshSpec for every vertex. That
		* is, a vertex buffer should be (attributes size * number of vertices) in
		* length to be valid. Note that currently implementation will have a CPU
		* backed buffer generated.
		* @param vertexCount the number of vertices represented in the vertexBuffer and mesh.
		* @param bounds bounds of the mesh object.
		* @return a new Mesh object.
		*/
		@@ -70,13 +75,20 @@ public class Mesh {
		}

		/**
		* Generates an indexed {@link Mesh} object.
		* Generates a {@link Mesh} object.
		*
		* @param meshSpec {@link MeshSpecification} used when generating the mesh.
		* @param mode {@link Mode} enum
		* @param vertexBuffer vertex buffer representing through {@link Buffer}.
		* @param vertexCount the number of vertices represented in the vertexBuffer.
		* @param indexBuffer index buffer representing through {@link ShortBuffer}.
		* @param vertexBuffer vertex buffer representing through {@link Buffer}. This provides the data
		* for all attributes provided within the meshSpec for every vertex. That
		* is, a vertex buffer should be (attributes size * number of vertices) in
		* length to be valid. Note that currently implementation will have a CPU
		* backed buffer generated.
		* @param vertexCount the number of vertices represented in the vertexBuffer and mesh.
		* @param indexBuffer index buffer representing through {@link ShortBuffer}. Indices are
		* required to be 16 bits, so ShortBuffer is necessary. Note that
		* currently implementation will have a CPU
		* backed buffer generated.
		* @param bounds bounds of the mesh object.
		* @return a new Mesh object.
		*/
		@@ -93,7 +105,10 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform color value corresponding to the shader assigned to the mesh. If the shader
		* does not have a uniform with that name or if the uniform is declared with a type other than
		* vec3 or vec4 and corresponding layout(color) annotation then an IllegalArgumentExcepton is
		* thrown.
		*
		* @param uniformName name matching the color uniform declared in the shader program.
		* @param color the provided sRGB color will be converted into the shader program's output
		@@ -104,7 +119,10 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform color value corresponding to the shader assigned to the mesh. If the shader
		* does not have a uniform with that name or if the uniform is declared with a type other than
		* vec3 or vec4 and corresponding layout(color) annotation then an IllegalArgumentExcepton is
		* thrown.
		*
		* @param uniformName name matching the color uniform declared in the shader program.
		* @param color the provided sRGB color will be converted into the shader program's output
		@@ -116,7 +134,10 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform color value corresponding to the shader assigned to the mesh. If the shader
		* does not have a uniform with that name or if the uniform is declared with a type other than
		* vec3 or vec4 and corresponding layout(color) annotation then an IllegalArgumentExcepton is
		* thrown.
		*
		* @param uniformName name matching the color uniform declared in the shader program.
		* @param color the provided sRGB color will be converted into the shader program's output
		@@ -132,7 +153,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than a
		* float or float[1] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the float uniform declared in the shader program.
		* @param value float value corresponding to the float uniform with the given name.
		@@ -142,7 +165,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than a
		* vec2 or float[2] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the float uniform declared in the shader program.
		* @param value1 first float value corresponding to the float uniform with the given name.
		@@ -153,7 +178,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than a
		* vec3 or float[3] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the float uniform declared in the shader program.
		* @param value1 first float value corresponding to the float uniform with the given name.
		@@ -166,7 +193,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than a
		* vec4 or float[4] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the float uniform declared in the shader program.
		* @param value1 first float value corresponding to the float uniform with the given name.
		@@ -180,7 +209,10 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than a
		* float (for N=1), vecN, or float[N], where N is the length of the values param, then an
		* IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the float uniform declared in the shader program.
		* @param values float value corresponding to the vec4 float uniform with the given name.
		@@ -210,7 +242,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than int
		* or int[1] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the int uniform delcared in the shader program.
		* @param value value corresponding to the int uniform with the given name.
		@@ -220,7 +254,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than ivec2
		* or int[2] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the int uniform delcared in the shader program.
		* @param value1 first value corresponding to the int uniform with the given name.
		@@ -231,7 +267,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than ivec3
		* or int[3] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the int uniform delcared in the shader program.
		* @param value1 first value corresponding to the int uniform with the given name.
		@@ -243,7 +281,9 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than ivec4
		* or int[4] then an IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the int uniform delcared in the shader program.
		* @param value1 first value corresponding to the int uniform with the given name.
		@@ -256,7 +296,10 @@ public class Mesh {
		}

		/**
		* Sets the uniform color value corresponding to the shader assigned to the mesh.
		* Sets the uniform value corresponding to the shader assigned to the mesh. If the shader does
		* not have a uniform with that name or if the uniform is declared with a type other than an
		* int (for N=1), ivecN, or int[N], where N is the length of the values param, then an
		* IllegalArgumentException is thrown.
		*
		* @param uniformName name matching the int uniform delcared in the shader program.
		* @param values int values corresponding to the vec4 int uniform with the given name.

graphics/java/android/graphics/MeshSpecification.java

+68 −13

Original line number	Diff line number	Diff line
		@@ -25,7 +25,7 @@ import libcore.util.NativeAllocationRegistry;
		* generates a {@link MeshSpecification} via the Make method, where multiple parameters to set up
		* the mesh are supplied, including attributes, vertex stride, varyings, and
		* vertex/fragment shaders. There are also additional methods to provide an optional
		* {@link ColorSpace} as well as an alpha type.
		* {@link ColorSpace} as well as an {@link AlphaType}.
		*
		* Note that there are several limitations on various mesh specifications:
		* 1. The max amount of attributes allowed is 8.
		@@ -43,15 +43,30 @@ public class MeshSpecification {

		/**
		* Constants for {@link #make(Attribute[], int, Varying[], String, String, ColorSpace, int)}
		* to determine alpha type
		* to determine alpha type. Describes how to interpret the alpha component of a pixel.
		*/
		@IntDef({UNKNOWN, OPAQUE, PREMUL, UNPREMULT})
		public @interface AlphaType {
		}

		/**
		* uninitialized.
		*/
		public static final int UNKNOWN = 0;

		/**
		* Pixel is opaque.
		*/
		public static final int OPAQUE = 1;

		/**
		* Pixel components are premultiplied by alpha.
		*/
		public static final int PREMUL = 2;

		/**
		* Pixel components are independent of alpha.
		*/
		public static final int UNPREMULT = 3;

		/**
		@@ -61,15 +76,41 @@ public class MeshSpecification {
		public @interface Type {
		}

		/**
		* Represents one float. Its equivalent shader type is float.
		*/
		public static final int FLOAT = 0;

		/**
		* Represents two floats. Its equivalent shader type is float2.
		*/
		public static final int FLOAT2 = 1;

		/**
		* Represents three floats. Its equivalent shader type is float3.
		*/
		public static final int FLOAT3 = 2;

		/**
		* Represents four floats. Its equivalent shader type is float4.
		*/
		public static final int FLOAT4 = 3;

		/**
		* Represents four bytes. Its equivalent shader type is half4.
		*/
		public static final int UBYTE4 = 4;

		/**
		* Data class to represent a single attribute in a shader. Note that type parameter must be
		* one of {@link #FLOAT}, {@link #FLOAT2}, {@link #FLOAT3}, {@link #FLOAT4}, or {@link #UBYTE4}.
		*
		* Note that offset is the offset in number of bytes. For example, if we had two attributes
		*
		* Float3 att1
		* Float att2
		*
		* att1 would have an offset of 0, while att2 would have an offset of 12 bytes.
		*/
		public static class Attribute {
		@Type
		@@ -106,14 +147,19 @@ public class MeshSpecification {
		}

		/**
		* Creates a {@link MeshSpecification} object.
		* Creates a {@link MeshSpecification} object for use within {@link Mesh}.
		*
		* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of
		* 8.
		* @param vertexStride length of vertex stride. Max of 1024 is accepted.
		* @param vertexStride length of vertex stride in bytes. This should be the size of a single
		* vertex' attributes. Max of 1024 is accepted.
		* @param varyings List of varyings represented by {@link Varying}. Can hold a max of 6.
		* @param vertexShader vertex shader to be supplied to the mesh.
		* @param fragmentShader fragment shader to be suppied to the mesh.
		* Note that `position` is provided by default, does not need to be
		* provided in the list, and does not count towards
		* the 6 varyings allowed.
		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
		* varying is set within the shader to get proper results.
		* @param fragmentShader fragment shader to be supplied to the mesh.
		* @return {@link MeshSpecification} object for use when creating {@link Mesh}
		*/
		public static MeshSpecification make(Attribute[] attributes, int vertexStride,
		@@ -131,10 +177,14 @@ public class MeshSpecification {
		*
		* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of
		* 8.
		* @param vertexStride length of vertex stride. Max of 1024 is accepted.
		* @param varyings List of varyings represented by {@link Varying}. Can hold a max of
		* 6.
		* @param vertexShader vertex shader to be supplied to the mesh.
		* @param vertexStride length of vertex stride in bytes. This should be the size of a single
		* vertex' attributes. Max of 1024 is accepted.
		* @param varyings List of varyings represented by {@link Varying}. Can hold a max of 6.
		* Note that `position` is provided by default, does not need to be
		* provided in the list, and does not count towards
		* the 6 varyings allowed.
		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
		* varying is set within the shader to get proper results.
		* @param fragmentShader fragment shader to be supplied to the mesh.
		* @param colorSpace {@link ColorSpace} to tell what color space to work in.
		* @return {@link MeshSpecification} object for use when creating {@link Mesh}
		@@ -154,10 +204,15 @@ public class MeshSpecification {
		*
		* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of
		* 8.
		* @param vertexStride length of vertex stride. Max of 1024 is accepted.
		* @param vertexStride length of vertex stride in bytes. This should be the size of a single
		* vertex' attributes. Max of 1024 is accepted.
		* @param varyings List of varyings represented by {@link Varying}. Can hold a max of 6.
		* @param vertexShader vertex shader code to be supplied to the mesh.
		* @param fragmentShader fragment shader code to be suppied to the mesh.
		* Note that `position` is provided by default, does not need to be
		* provided in the list, and does not count towards
		* the 6 varyings allowed.
		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
		* varying is set within the shader to get proper results.
		* @param fragmentShader fragment shader to be supplied to the mesh.
		* @param colorSpace {@link ColorSpace} to tell what color space to work in.
		* @param alphaType Describes how to interpret the alpha component for a pixel. Must be
		* one of {@link AlphaType} values.