Merge "Improve MeshSpecification docs" into udc-dev am: a26d9e2519 (ddf661b1) · Commits · e / os / android_frameworks_base

graphics/java/android/graphics/MeshSpecification.java

+66 −9

Original line number	Original line	Diff line number	Diff line
	@@ -28,11 +28,40 @@ import java.lang.annotation.Retention;
	import java.lang.annotation.RetentionPolicy;		import java.lang.annotation.RetentionPolicy;

	/**		/**
	* Class responsible for holding specifications for {@link Mesh} creations. This class		* Class responsible for holding specifications for {@link Mesh} creations. This class generates a
	* generates a {@link MeshSpecification} via the Make method, where multiple parameters to set up		* {@link MeshSpecification} via the
	* the mesh are supplied, including attributes, vertex stride, varyings, and		* {@link MeshSpecification#make(Attribute[], int, Varying[], String, String)} method,
	* vertex/fragment shaders. There are also additional methods to provide an optional		* where multiple parameters to set up the mesh are supplied, including attributes, vertex stride,
	* {@link ColorSpace} as well as an alpha type.		* {@link Varying}, and vertex/fragment shaders. There are also additional methods to provide an
			* optional {@link ColorSpace} as well as an alpha type.
			*
			* For example a vertex shader that leverages a {@link Varying} may look like the following:
			*
			* <pre>
			* Varyings main(const Attributes attributes) {
			* Varyings varyings;
			* varyings.position = attributes.position;
			* return varyings;
			* }
			* </pre>
			*
			* The corresponding fragment shader that may consume the varying look like the following:
			*
			* <pre>
			* float2 main(const Varyings varyings, out float4 color) {
			* color = vec4(1.0, 0.0, 0.0, 1.0);
			* return varyings.position;
			* }
			* </pre>
			*
			* The color returned from this fragment shader is blended with the other parameters that are
			* configured on the Paint object (ex. {@link Paint#setBlendMode(BlendMode)} used to draw the mesh.
			*
			* The position returned in the fragment shader can be consumed by any following fragment shaders in
			* the shader chain.
			*
			* See https://developer.android.com/develop/ui/views/graphics/agsl for more information
			* regarding Android Graphics Shader Language.
	*		*
	* Note that there are several limitations on various mesh specifications:		* Note that there are several limitations on various mesh specifications:
	* 1. The max amount of attributes allowed is 8.		* 1. The max amount of attributes allowed is 8.
	@@ -118,7 +147,11 @@ public class MeshSpecification {
	public static final int TYPE_UBYTE4 = 4;		public static final int TYPE_UBYTE4 = 4;

	/**		/**
	* Data class to represent a single attribute in a shader.		* Data class to represent a single attribute in a shader. An attribute is a variable that
			* accompanies a vertex, this can be a color or texture coordinates.
			*
			* See https://developer.android.com/develop/ui/views/graphics/agsl for more information
			* regarding Android Graphics Shader Language.
	*		*
	* Note that offset is the offset in number of bytes. For example, if we had two attributes		* Note that offset is the offset in number of bytes. For example, if we had two attributes
	*		*
	@@ -128,6 +161,10 @@ public class MeshSpecification {
	* </pre>		* </pre>
	*		*
	* att1 would have an offset of 0, while att2 would have an offset of 12 bytes.		* att1 would have an offset of 0, while att2 would have an offset of 12 bytes.
			*
			* This is consumed as part of
			* {@link MeshSpecification#make(Attribute[], int, Varying[], String, String, ColorSpace, int)}
			* to create a {@link MeshSpecification} instance.
	*/		*/
	public static class Attribute {		public static class Attribute {
	@Type		@Type
	@@ -175,7 +212,15 @@ public class MeshSpecification {
	}		}

	/**		/**
	* Data class to represent a single varying variable.		* Data class to represent a single varying variable. A Varying variable can be altered by the
			* vertex shader defined on the mesh but not by the fragment shader defined by AGSL.
			*
			* See https://developer.android.com/develop/ui/views/graphics/agsl for more information
			* regarding Android Graphics Shader Language.
			*
			* This is consumed as part of
			* {@link MeshSpecification#make(Attribute[], int, Varying[], String, String, ColorSpace, int)}
			* to create a {@link MeshSpecification} instance.
	*/		*/
	public static class Varying {		public static class Varying {
	@Type		@Type
	@@ -220,7 +265,7 @@ public class MeshSpecification {

	/**		/**
	* Creates a {@link MeshSpecification} object for use within {@link Mesh}. This uses a default		* Creates a {@link MeshSpecification} object for use within {@link Mesh}. This uses a default
	* color space of {@link ColorSpace.Named#SRGB} and {@link AlphaType} of		* color space of {@link ColorSpace.Named#SRGB} and alphaType of
	* {@link #ALPHA_TYPE_PREMULTIPLIED}.		* {@link #ALPHA_TYPE_PREMULTIPLIED}.
	*		*
	* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of		* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of
	@@ -233,7 +278,11 @@ public class MeshSpecification {
	* the 6 varyings allowed.		* the 6 varyings allowed.
	* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
	* varying is set within the shader to get proper results.		* varying is set within the shader to get proper results.
			* See {@link MeshSpecification} for an example vertex shader
			* implementation
	* @param fragmentShader fragment shader to be supplied to the mesh.		* @param fragmentShader fragment shader to be supplied to the mesh.
			* See {@link MeshSpecification} for an example fragment shader
			* implementation
	* @return {@link MeshSpecification} object for use when creating {@link Mesh}		* @return {@link MeshSpecification} object for use when creating {@link Mesh}
	*/		*/
	@NonNull		@NonNull
	@@ -253,7 +302,7 @@ public class MeshSpecification {
	}		}

	/**		/**
	* Creates a {@link MeshSpecification} object. This uses a default {@link AlphaType} of		* Creates a {@link MeshSpecification} object. This uses a default alphaType of
	* {@link #ALPHA_TYPE_PREMULTIPLIED}.		* {@link #ALPHA_TYPE_PREMULTIPLIED}.
	*		*
	* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of		* @param attributes list of attributes represented by {@link Attribute}. Can hold a max of
	@@ -266,7 +315,11 @@ public class MeshSpecification {
	* the 6 varyings allowed.		* the 6 varyings allowed.
	* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
	* varying is set within the shader to get proper results.		* varying is set within the shader to get proper results.
			* See {@link MeshSpecification} for an example vertex shader
			* implementation
	* @param fragmentShader fragment shader to be supplied to the mesh.		* @param fragmentShader fragment shader to be supplied to the mesh.
			* See {@link MeshSpecification} for an example fragment shader
			* implementation
	* @param colorSpace {@link ColorSpace} to tell what color space to work in.		* @param colorSpace {@link ColorSpace} to tell what color space to work in.
	* @return {@link MeshSpecification} object for use when creating {@link Mesh}		* @return {@link MeshSpecification} object for use when creating {@link Mesh}
	*/		*/
	@@ -301,7 +354,11 @@ public class MeshSpecification {
	* the 6 varyings allowed.		* the 6 varyings allowed.
	* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position		* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
	* varying is set within the shader to get proper results.		* varying is set within the shader to get proper results.
			* See {@link MeshSpecification} for an example vertex shader
			* implementation
	* @param fragmentShader fragment shader to be supplied to the mesh.		* @param fragmentShader fragment shader to be supplied to the mesh.
			* See {@link MeshSpecification} for an example fragment shader
			* implementation
	* @param colorSpace {@link ColorSpace} to tell what color space to work in.		* @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		* @param alphaType Describes how to interpret the alpha component for a pixel. Must be
	* one of		* one of