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

Updated Mesh documentation

Browse Source 
Updated Mesh and MeshSpecification documentation to better describe parameters/important method features.

Bug: b/253321460
Test: none
Change-Id: I87fb2cdc2ca36f891c339c77b2ed05dee4b84fee
This commit is contained in:
Angel Aguayo
2022-11-30 19:34:30 +00:00
parent 03d6100517
commit 4a39f27868
2 changed files with 131 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
graphics/java/android/graphics/Mesh.java
View File

@@ -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.

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

@@ -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.