diff --git a/android/filament-android/src/main/java/com/google/android/filament/Box.java b/android/filament-android/src/main/java/com/google/android/filament/Box.java index 93bef14db3..b5fb057506 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/Box.java +++ b/android/filament-android/src/main/java/com/google/android/filament/Box.java @@ -19,12 +19,25 @@ package com.google.android.filament; import android.support.annotation.NonNull; import android.support.annotation.Size; +/** + * An axis-aligned 3D box represented by its center and half-extent. + * + * The half-extent is a vector representing the distance from the center to the edge of the box in + * each dimension. For example, a box of size 2 units in X, 4 units in Y, and 10 units in Z would + * have a half-extent of (1, 2, 5). + */ public class Box { private final float[] mCenter = new float[3]; private final float[] mHalfExtent = new float[3]; + /** + * Default-initializes the 3D box to have a center and half-extent of (0,0,0). + */ public Box() { } + /** + * Initializes the 3D box from its center and half-extent. + */ public Box(float centerX, float centerY, float centerZ, float halfExtentX, float halfExtentY, float halfExtentZ) { mCenter[0] = centerX; @@ -35,6 +48,13 @@ public class Box { mHalfExtent[2] = halfExtentZ; } + /** + * Initializes the 3D box from its center and half-extent. + * + * @param center a float array with XYZ coordinates representing the center of the box + * @param halfExtent a float array with XYZ coordinates representing half the size of the box in + * each dimension + */ public Box(@NonNull @Size(min = 3) float[] center, @NonNull @Size(min = 3) float[] halfExtent) { mCenter[0] = center[0]; mCenter[1] = center[1]; @@ -44,21 +64,37 @@ public class Box { mHalfExtent[2] = halfExtent[2]; } + /** + * Sets the center of of the 3D box. + */ public void setCenter(float centerX, float centerY, float centerZ) { mCenter[0] = centerX; mCenter[1] = centerY; mCenter[2] = centerZ; } + /** + * Sets the half-extent of the 3D box. + */ public void setHalfExtent(float halfExtentX, float halfExtentY, float halfExtentZ) { mHalfExtent[0] = halfExtentX; mHalfExtent[1] = halfExtentY; mHalfExtent[2] = halfExtentZ; } + /** + * Returns the center of the 3D box. + * + * @return an XYZ float array of size 3 + */ @NonNull @Size(min = 3) public float[] getCenter() { return mCenter; } + /** + * Returns the half-extent from the center of the 3D box. + * + * @return an XYZ float array of size 3 + */ @NonNull @Size(min = 3) public float[] getHalfExtent() { return mHalfExtent; } } diff --git a/android/filament-android/src/main/java/com/google/android/filament/Colors.java b/android/filament-android/src/main/java/com/google/android/filament/Colors.java index 72c3dbb0bb..a38daca1a1 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/Colors.java +++ b/android/filament-android/src/main/java/com/google/android/filament/Colors.java @@ -28,6 +28,9 @@ import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.PARAMETER; import static java.lang.annotation.RetentionPolicy.SOURCE; +/** + * Utilities to manipulate and convert colors. + */ public class Colors { private Colors() { } @@ -37,23 +40,67 @@ public class Colors { public @interface LinearColor { } + /** + * Types of RGB colors. + */ public enum RgbType { + /** The color is defined in sRGB space. */ SRGB, + + /** The color is defined in linear space. */ LINEAR } + /** + * Types of RGBA colors. + */ public enum RgbaType { + /** + * The color is defined in sRGB space and the RGB values have not been premultiplied by the + * alpha (for instance, a 50% transparent red is <1,0,0,0.5>). + */ SRGB, + + /** + * The color is defined in linear space and the RGB values have not been premultiplied by + * the alpha (for instance, a 50% transparent red is <1,0,0,0.5>). + */ LINEAR, + + /** + * The color is defined in sRGB space and the RGB values have been premultiplied by the + * alpha (for instance, a 50% transparent red is <0.5,0,0,0.5>). + */ PREMULTIPLIED_SRGB, + + /** + * The color is defined in linear space and the RGB values have been premultiplied by the + * alpha (for instance, a 50% transparent red is <0.5,0,0,0.5>). + */ PREMULTIPLIED_LINEAR } + /** + * Type of color conversion to use when converting to/from sRGB and linear spaces. + */ public enum Conversion { + /** Accurate conversion using the sRGB standard. */ ACCURATE, + + /** Fast conversion using a simple gamma 2.2 curve. */ FAST } + /** + * Converts an RGB color to linear space, the conversion depends on the specified type. + * + * @param type the color space of the RGB color values provided + * @param r the red component + * @param g the green component + * @param b the blue component + * + * @return an RGB float array of size 3 with the result of the conversion + */ @NonNull @Size(3) @LinearColor @@ -61,6 +108,14 @@ public class Colors { return toLinear(type, new float[] { r, g, b }); } + /** + * Converts an RGB color to linear space, the conversion depends on the specified type. + * + * @param type the color space of the RGB color values provided + * @param rgb an RGB float array of size 3, will be modified + * + * @return the passed-in rgb array, after applying the conversion + */ @NonNull @Size(min = 3) @LinearColor @@ -68,6 +123,17 @@ public class Colors { return (type == RgbType.LINEAR) ? rgb : toLinear(Conversion.ACCURATE, rgb); } + /** + * Converts an RGBA color to linear space, with pre-multiplied alpha. + * + * @param type the color space and type of RGBA color values provided + * @param r the red component + * @param g the green component + * @param b the blue component + * @param a the alpha component + * + * @return an RGBA float array of size 4 with the result of the conversion + */ @NonNull @Size(4) @LinearColor @@ -75,6 +141,14 @@ public class Colors { return toLinear(type, new float[] { r, g, b, a }); } + /** + * Converts an RGBA color to linear space, with pre-multiplied alpha. + * + * @param type the color space of the RGBA color values provided + * @param rgba an RGBA float array of size 4, will be modified + * + * @return the passed-in rgba array, after applying the conversion + */ @NonNull @Size(min = 4) @LinearColor @@ -97,6 +171,15 @@ public class Colors { return rgba; } + /** + * Converts an RGB color in sRGB space to an RGB color in linear space. + * + * @param conversion the conversion algorithm to use + * @param rgb an RGB float array of at least size 3, will be modified + * + * @return the passed-in rgb array, after applying the conversion. The alpha + * channel, if present, is left unmodified. + */ @NonNull @LinearColor public static float[] toLinear(@NonNull Conversion conversion, @NonNull @Size(min = 3) float[] rgb) { @@ -116,6 +199,14 @@ public class Colors { return rgb; } + /** + * Converts a correlated color temperature to a linear RGB color in sRGB space. The temperature + * must be expressed in Kelvin and must be in the range 1,000K to 15,000K. + * + * @param temperature the temperature, in Kelvin + * + * @return an RGB float array of size 3 with the result of the conversion + */ @NonNull @Size(3) @LinearColor @@ -125,6 +216,14 @@ public class Colors { return color; } + /** + * Converts a CIE standard illuminant series D to a linear RGB color in sRGB space. The + * temperature must be expressed in Kelvin and must be in the range 4,000K to 25,000K. + * + * @param temperature the temperature, in Kelvin + * + * @return an RGB float array of size 3 with the result of the conversion + */ @NonNull @Size(3) @LinearColor diff --git a/android/filament-android/src/main/java/com/google/android/filament/MathUtils.java b/android/filament-android/src/main/java/com/google/android/filament/MathUtils.java index 25abfe4652..76fd2c4ec0 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/MathUtils.java +++ b/android/filament-android/src/main/java/com/google/android/filament/MathUtils.java @@ -23,6 +23,29 @@ import android.support.annotation.Size; public final class MathUtils { private MathUtils() { } + /** + * Packs the tangent frame represented by the specified tangent, bitangent, and normal into a + * quaternion. + * + *

+ * Reflection is preserved by encoding it as the sign of the w component in the resulting + * quaternion. Since -0 cannot always be represented on the GPU, this function computes a bias + * to ensure values are always either positive or negative, never 0. The bias is computed based + * on a per-element storage size of 2 bytes, making the resulting quaternion suitable for + * storage into an SNORM16 vector. + *

+ * + * @param tangentX the X component of the tangent + * @param tangentY the Y component of the tangent + * @param tangentZ the Z component of the tangent + * @param bitangentX the X component of the bitangent + * @param bitangentY the Y component of the bitangent + * @param bitangentZ the Z component of the bitangent + * @param normalX the X component of the normal + * @param normalY the Y component of the normal + * @param normalZ the Z component of the normal + * @param quaternion a float array of at least size 4 for the quaternion result to be stored + */ public static void packTangentFrame( float tangentX, float tangentY, float tangentZ, float bitangentX, float bitangentY, float bitangentZ, @@ -34,6 +57,30 @@ public final class MathUtils { normalX, normalY, normalZ, quaternion, 0); } + /** + * Packs the tangent frame represented by the specified tangent, bitangent, and normal into a + * quaternion. + * + *

+ * Reflection is preserved by encoding it as the sign of the w component in the resulting + * quaternion. Since -0 cannot always be represented on the GPU, this function computes a bias + * to ensure values are always either positive or negative, never 0. The bias is computed based + * on a per-element storage size of 2 bytes, making the resulting quaternion suitable for + * storage into an SNORM16 vector. + *

+ * + * @param tangentX the X component of the tangent + * @param tangentY the Y component of the tangent + * @param tangentZ the Z component of the tangent + * @param bitangentX the X component of the bitangent + * @param bitangentY the Y component of the bitangent + * @param bitangentZ the Z component of the bitangent + * @param normalX the X component of the normal + * @param normalY the Y component of the normal + * @param normalZ the Z component of the normal + * @param quaternion a float array of at least size 4 for the quaternion result to be stored + * @param offset offset, in elements, into the quaternion array to store the results + */ public static void packTangentFrame( float tangentX, float tangentY, float tangentZ, float bitangentX, float bitangentY, float bitangentZ, diff --git a/java/filament/CMakeLists.txt b/java/filament/CMakeLists.txt index b66d440b37..f3d8e11e89 100644 --- a/java/filament/CMakeLists.txt +++ b/java/filament/CMakeLists.txt @@ -51,6 +51,7 @@ set(JNI_SOURCE_FILES ${FILAMENT_DIR}/src/main/cpp/LightManager.cpp ${FILAMENT_DIR}/src/main/cpp/Material.cpp ${FILAMENT_DIR}/src/main/cpp/MaterialInstance.cpp + ${FILAMENT_DIR}/src/main/cpp/MathUtils.cpp ${FILAMENT_DIR}/src/main/cpp/NativeSurface.cpp ${FILAMENT_DIR}/src/main/cpp/RenderableManager.cpp ${FILAMENT_DIR}/src/main/cpp/Renderer.cpp @@ -127,6 +128,7 @@ set(JAVA_SOURCE_FILES ${FILAMENT_JAVA_DIR}/com/google/android/filament/LightManager.java ${FILAMENT_JAVA_DIR}/com/google/android/filament/Material.java ${FILAMENT_JAVA_DIR}/com/google/android/filament/MaterialInstance.java + ${FILAMENT_JAVA_DIR}/com/google/android/filament/MathUtils.java ${FILAMENT_JAVA_DIR}/com/google/android/filament/NativeSurface.java ${FILAMENT_JAVA_DIR}/com/google/android/filament/NioUtils.java ${FILAMENT_JAVA_DIR}/com/google/android/filament/Platform.java