From 4a39f27868d094a1b5c26bb7c531cfab436b0c10 Mon Sep 17 00:00:00 2001 From: Angel Aguayo Date: Wed, 30 Nov 2022 19:34:30 +0000 Subject: [PATCH] Updated Mesh documentation Updated Mesh and MeshSpecification documentation to better describe parameters/important method features. Bug: b/253321460 Test: none Change-Id: I87fb2cdc2ca36f891c339c77b2ed05dee4b84fee --- graphics/java/android/graphics/Mesh.java | 83 ++++++++++++++----- .../android/graphics/MeshSpecification.java | 81 +++++++++++++++--- 2 files changed, 131 insertions(+), 33 deletions(-) diff --git a/graphics/java/android/graphics/Mesh.java b/graphics/java/android/graphics/Mesh.java index f32e0ee0cc79a..1f693166ecf04 100644 --- a/graphics/java/android/graphics/Mesh.java +++ b/graphics/java/android/graphics/Mesh.java @@ -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. diff --git a/graphics/java/android/graphics/MeshSpecification.java b/graphics/java/android/graphics/MeshSpecification.java index 45c13affac146..dd8fb7ab23700 100644 --- a/graphics/java/android/graphics/MeshSpecification.java +++ b/graphics/java/android/graphics/MeshSpecification.java @@ -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.