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