Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve MeshSpecification docs

Browse Source 
Added more docs and code snippets
to varying and attribute classes within
MeshSpecification.

Fixes: 279785743
Test: re-ran CTS tests
Change-Id: Ic370fb1547c7b2f83a221d614c35ffdd9f4e0b8b
This commit is contained in:
Nader Jawad
2023-04-27 16:01:39 -07:00
parent 682209e24f
commit 4423b52a91
1 changed files with 66 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
graphics/java/android/graphics/MeshSpecification.java
View File

@@ -28,11 +28,40 @@ import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Class responsible for holding specifications for {@link Mesh} creations. This class
* 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.
* Class responsible for holding specifications for {@link Mesh} creations. This class generates a
* {@link MeshSpecification} via the
* {@link MeshSpecification#make(Attribute[], int, Varying[], String, String)} method,
* where multiple parameters to set up the mesh are supplied, including attributes, vertex stride,
* {@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:
* 1. The max amount of attributes allowed is 8.
@@ -118,7 +147,11 @@ public class MeshSpecification {
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
*
@@ -128,6 +161,10 @@ public class MeshSpecification {
* </pre>
*
* 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 {
@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 {
@Type
@@ -220,7 +265,7 @@ public class MeshSpecification {
/**
* 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}.
*
* @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.
* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
* 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.
* See {@link MeshSpecification} for an example fragment shader
* implementation
* @return {@link MeshSpecification} object for use when creating {@link Mesh}
*/
@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}.
*
* @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.
* @param vertexShader vertex shader to be supplied to the mesh. Ensure that the position
* 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.
* See {@link MeshSpecification} for an example fragment shader
* implementation
* @param colorSpace {@link ColorSpace} to tell what color space to work in.
* @return {@link MeshSpecification} object for use when creating {@link Mesh}
*/
@@ -301,7 +354,11 @@ public class MeshSpecification {
* 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.
* See {@link MeshSpecification} for an example vertex shader
* implementation
* @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 alphaType Describes how to interpret the alpha component for a pixel. Must be
* one of