From 340f6d721ac663ffff67790460eadd933d14fcd3 Mon Sep 17 00:00:00 2001
From: Mathias Agopian The These formats are used to specify a texture's internal storage format. A The internal format specifies how texels are stored (which may be different from how
+ * they're specified in {@link #setImage}). {@link InternalFormat InternalFormat} specifies
+ * both the color components and the data type used. This This This This Typically the external image is OS specific, and can be a video or camera frame.
+ * There are many restrictions when using an external image as a texture, such as: On iOS the following pixel formats are supported: IndirectLight with.
*
- * @return pointer to the newly created object or nullptr if exceptions are disabled and
- * an error occurred.
+ * @return A newly created IndirectLight
*
* @exception IllegalStateException if a parameter to a builder function was invalid.
*/
diff --git a/android/filament-android/src/main/java/com/google/android/filament/Texture.java b/android/filament-android/src/main/java/com/google/android/filament/Texture.java
index a5b5b24681..6b9b478dfd 100644
--- a/android/filament-android/src/main/java/com/google/android/filament/Texture.java
+++ b/android/filament-android/src/main/java/com/google/android/filament/Texture.java
@@ -29,6 +29,47 @@ import java.nio.ByteBuffer;
import static com.google.android.filament.Texture.Type.COMPRESSED;
+/**
+ * Texture
+ * Texture class supports:
+ *
+ *
+ *
+ * Usage example
+ *
+ * A Texture object is created using the {@link Texture.Builder} and destroyed by
+ * calling {@link Engine#destroyTexture}. They're bound using {@link MaterialInstance#setParameter}.
+ *
+ *
+ * Engine engine = Engine.create();
+ *
+ * Material material = new Material.Builder()
+ * .payload( ... )
+ * .build(ending);
+ *
+ * MaterialInstance mi = material.getDefaultInstance();
+ *
+ * Texture texture = new Texture.Builder()
+ * .width(64)
+ * .height(64)
+ * .build(engine);
+ *
+ *
+ * texture.setImage(engine, 0,
+ * new Texture.PixelBufferDescriptor( ... ));
+ *
+ * mi.setParameter("parameterName", texture, new TextureSampler());
+ *
+ *
+ * @see #setImage
+ * @see PixelBufferDescriptor
+ * @see MaterialInstance#setParameter(String, Texture, TextureSampler)
+ */
public class Texture {
private long mNativeObject;
@@ -37,12 +78,95 @@ public class Texture {
mNativeObject = nativeTexture;
}
+ /**
+ * Type of sampler
+ */
public enum Sampler {
+ /** 2D sampler */
SAMPLER_2D,
+ /** Cubemap sampler */
SAMPLER_CUBEMAP,
+ /** External texture sampler */
SAMPLER_EXTERNAL
}
+ /**
+ * Internal texel formats
+ *
+ * Enumerants syntax format
+ *
+ * [components][size][type]
+ * components : List of stored components by this format
+ * size : Size in bit of each component
+ * type : Type this format is stored as
+ *
+ *
+ *
+ *
+ * Name Component
+ * R Linear Red
+ * RG Linear Red, Green
+ * RGB Linear Red, Green, Blue
+ * RGBA Linear Red, Green Blue, Alpha
+ * SRGB sRGB encoded Red, Green, Blue
+ * DEPTH Depth
+ * STENCIL Stencil
+ *
+ *
+ *
+ *
+ * Name Type
+ * (none) Unsigned Normalized Integer [0, 1]
+ * _SNORM Signed Normalized Integer [-1, 1]
+ * UI Unsigned Integer [0, 2size]
+ * I Signed Integer [-2size-1, 2size-1-1]
+ * F Floating-point
+ *
+ * Special color formats
+ *
+ * There are a few special color formats that don't follow the convention above:
+ *
+ *
+ *
+ *
+ * Name Format
+ * RGB565 5-bits for R and B, 6-bits for G.
+ * RGB5_A1 5-bits for R, G and B, 1-bit for A.
+ * RGB10_A2 10-bits for R, G and B, 2-bits for A.
+ * RGB9_E5 Unsigned floating point. 9-bits mantissa for RGB, 5-bits shared exponent
+ * R11F_G11F_B10F Unsigned floating point. 6-bits mantissa, for R and G, 5-bits for B. 5-bits exponent.
+ * SRGB8_A8 sRGB 8-bits with linear 8-bits alpha.
+ * DEPTH24_STENCIL8 24-bits unsigned normalized integer depth, 8-bits stencil.
+ *
+ * Compressed texture formats
+ *
+ * Many compressed texture formats are supported as well, which include (but are not limited to)
+ * the following list:
+ *
+ *
+ *
+ *
+ * Name Format
+ * EAC_R11 Compresses R11UI
+ * EAC_R11_SIGNED Compresses R11I
+ * EAC_RG11 Compresses RG11UI
+ * EAC_RG11_SIGNED Compresses RG11I
+ * ETC2_RGB8 Compresses RGB8
+ * ETC2_SRGB8 compresses SRGB8
+ * ETC2_EAC_RGBA8 Compresses RGBA8
+ * ETC2_EAC_SRGBA8 Compresses SRGB8_A8
+ * ETC2_RGB8_A1 Compresses RGB8 with 1-bit alpha
+ * ETC2_SRGB8_A1 Compresses sRGB8 with 1-bit alpha PixelBufferDescriptor owns the memory buffer it references,
+ * therefore PixelBufferDescriptor cannot be copied, but can be moved.PixelBufferDescriptor releases ownership of the memory-buffer when it's
+ * destroyed.
+ *
+ * @see #setImage
+ */
public static class PixelBufferDescriptor {
public Buffer storage;
@@ -165,6 +329,20 @@ public class Texture {
* - Android: Handler, Executor
* - Other: Executor
*/
+
+ /**
+ * Creates a PixelBufferDescriptor
+ *
+ * @param storage CPU-side buffer containing the image data to upload into the texture
+ * @param format Pixel {@link Format format} of the CPU-side image
+ * @param type Pixel data {@link Type type} of the CPU-side image
+ * @param alignment Row-alignment in bytes of the CPU-side image (1 to 8 bytes)
+ * @param left Left coordinate in pixels of the CPU-side image
+ * @param top Top coordinate in pixels of the CPU-side image
+ * @param stride Stride in pixels of the CPU-side image (i.e. distance in pixels to the next row)
+ * @param handler An {@link java.util.concurrent.Executor Executor}. On Android this can also be a {@link android.os.Handler Handler}.
+ * @param callback A callback executed by handler when storage is no longer needed.
+ */
public PixelBufferDescriptor(@NonNull Buffer storage,
@NonNull Format format, @NonNull Type type,
@IntRange(from = 1, to = 8) int alignment,
@@ -182,17 +360,48 @@ public class Texture {
this.callback = callback;
}
+ /**
+ * Creates a PixelBufferDescriptor with some default values and no callback.
+ *
+ * @param storage CPU-side buffer containing the image data to upload into the texture
+ * @param format Pixel {@link Format format} of the CPU-side image
+ * @param type Pixel data {@link Type type} of the CPU-side image
+ *
+ * @see #setCallback
+ */
public PixelBufferDescriptor(@NonNull Buffer storage,
@NonNull Format format, @NonNull Type type) {
this(storage, format, type, 1, 0, 0, 0, null, null);
}
+ /**
+ * Creates a PixelBufferDescriptor with some default values and no callback.
+ *
+ * @param storage CPU-side buffer containing the image data to upload into the texture
+ * @param format Pixel {@link Format format} of the CPU-side image
+ * @param type Pixel data {@link Type type} of the CPU-side image
+ * @param alignment Row-alignment in bytes of the CPU-side image (1 to 8 bytes)
+ *
+ * @see #setCallback
+ */
public PixelBufferDescriptor(@NonNull Buffer storage,
@NonNull Format format, @NonNull Type type,
@IntRange(from = 1, to = 8) int alignment) {
this(storage, format, type, alignment, 0, 0, 0, null, null);
}
+ /**
+ * Creates a PixelBufferDescriptor with some default values and no callback.
+ *
+ * @param storage CPU-side buffer containing the image data to upload into the texture
+ * @param format Pixel {@link Format format} of the CPU-side image
+ * @param type Pixel data {@link Type type} of the CPU-side image
+ * @param alignment Row-alignment in bytes of the CPU-side image (1 to 8 bytes)
+ * @param left Left coordinate in pixels of the CPU-side image
+ * @param top Top coordinate in pixels of the CPU-side image
+ *
+ * @see #setCallback
+ */
public PixelBufferDescriptor(@NonNull Buffer storage,
@NonNull Format format, @NonNull Type type,
@IntRange(from = 1, to = 8) int alignment,
@@ -200,6 +409,14 @@ public class Texture {
this(storage, format, type, alignment, left, top, 0, null, null);
}
+ /**
+ *
+ * @param storage CPU-side buffer containing the image data to upload into the texture
+ * @param format Compressed pixel {@link CompressedFormat format} of the CPU-side image
+ * @param compressedSizeInBytes Size of the compressed data in bytes
+ *
+ * @see #setCallback
+ */
public PixelBufferDescriptor(@NonNull ByteBuffer storage,
@NonNull CompressedFormat format,
@IntRange(from = 0) int compressedSizeInBytes) {
@@ -211,9 +428,10 @@ public class Texture {
}
/**
- * Valid handler types:
- * - Android: Handler, Executor
- * - Other: Executor
+ * Set or replace the callback called when the CPU-side data is no longer needed.
+ *
+ * @param handler An {@link java.util.concurrent.Executor Executor}. On Android this can also be a {@link android.os.Handler Handler}.
+ * @param callback A callback executed by handler when storage is no longer needed.
*/
public void setCallback(@Nullable Object handler, @Nullable Runnable callback) {
this.handler = handler;
@@ -288,57 +506,109 @@ public class Texture {
}
}
+ /**
+ * Options of {@link #generatePrefilterMipmap}
+ */
public static class PrefilterOptions {
+ /** number of samples for roughness pre-filtering */
public int sampleCount = 8;
+ /** whether to generate a reflection map (mirror) */
public boolean mirror = true;
}
+ /**
+ * Checks whether a given format is supported for texturing in this {@link Engine}.
+ * This depends on the selected backend.
+ *
+ * @param engine {@link Engine} to test the {@link InternalFormat InternalFormat} against
+ * @param format format to check
+ * @return true if this format is supported for texturing.
+ */
public static boolean isTextureFormatSupported(@NonNull Engine engine,
@NonNull InternalFormat format) {
return nIsTextureFormatSupported(engine.getNativeObject(), format.ordinal());
}
+ /**
+ * Use Builder to construct a Texture object instance.
+ */
public static class Builder {
@SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
// Keep to finalize native resources
private final BuilderFinalizer mFinalizer;
private final long mNativeBuilder;
+ /**
+ * Use Builder to construct a Texture object instance.
+ */
public Builder() {
mNativeBuilder = nCreateBuilder();
mFinalizer = new BuilderFinalizer(mNativeBuilder);
}
+ /**
+ * Specifies the width of the texture in texels.
+ * @param width texture width in texels, must be at least 1. Default is 1.
+ * @return This Builder, for chaining calls.
+ */
@NonNull
public Builder width(@IntRange(from = 1) int width) {
nBuilderWidth(mNativeBuilder, width);
return this;
}
+ /**
+ * Specifies the height of the texture in texels.
+ * @param height texture height in texels, must be at least 1. Default is 1.
+ * @return This Builder, for chaining calls.
+ */
@NonNull
public Builder height(@IntRange(from = 1) int height) {
nBuilderHeight(mNativeBuilder, height);
return this;
}
+ /**
+ * Specifies the texture's number of layers. This creates a 3D texture.
+ * @param depth texture number of layer, must be at least 1. Default is 1.
+ * @return This Builder, for chaining calls.
+ */
@NonNull
public Builder depth(@IntRange(from = 1) int depth) {
nBuilderDepth(mNativeBuilder, depth);
return this;
}
+ /**
+ * Specifies the number of mipmap levels
+ * @param levels must be at least 1 and less or equal to floor(log2(max(width, height))) + 1. Default is 1.
+ * @return This Builder, for chaining calls.
+ */
@NonNull
public Builder levels(@IntRange(from = 1) int levels) {
nBuilderLevels(mNativeBuilder, levels);
return this;
}
+ /**
+ * Specifies the type of sampler to use.
+ * @param target {@link Sampler Sampler} type
+ * @return This Builder, for chaining calls.
+ */
@NonNull
public Builder sampler(@NonNull Sampler target) {
nBuilderSampler(mNativeBuilder, target.ordinal());
return this;
}
+ /**
+ * Specifies the texture's internal format.
+ * Texture instance.
+ * @param engine The {@link Engine} to associate this Texture with.
+ * @return A newly created Texture
+ * @exception IllegalStateException if a parameter to a builder function was invalid.
+ * A mode detailed message about the error is output in the system log.
+ */
@NonNull
public Texture build(@NonNull Engine engine) {
long nativeTexture = nBuilderBuild(mNativeBuilder, engine.getNativeObject());
@@ -382,38 +659,71 @@ public class Texture {
}
}
+ /**
+ * A bitmask to specify how the texture will be used.
+ */
public static class Usage {
+ /** The texture will be used as a color attachment */
public static final int COLOR_ATTACHMENT = 0x1;
+ /** The texture will be used as a depth attachment */
public static final int DEPTH_ATTACHMENT = 0x2;
+ /** The texture will be used as a stencil attachment */
public static final int STENCIL_ATTACHMENT = 0x4;
+ /** The texture content can be set with {@link #setImage} */
public static final int UPLOADABLE = 0x8;
+ /** The texture can be read from a shader or blitted from */
public static final int SAMPLEABLE = 0x10;
+ /** by default textures are UPLOADABLE and SAMPLEABLE*/
public static final int DEFAULT = UPLOADABLE | SAMPLEABLE;
}
public static final int BASE_LEVEL = 0;
+ /**
+ * Queries the width of a given level of this texture.
+ * @param level to query the with of. Must be between 0 and {@link #getLevels}
+ * @return The width in texel of the given level
+ */
public int getWidth(@IntRange(from = 0) int level) {
return nGetWidth(getNativeObject(), level);
}
+ /**
+ * Queries the height of a given level of this texture.
+ * @param level to query the height of. Must be between 0 and {@link #getLevels}
+ * @return The height in texel of the given level
+ */
public int getHeight(@IntRange(from = 0) int level) {
return nGetHeight(getNativeObject(), level);
}
+ /**
+ * Queries the number of layers of given level of this texture has.
+ * @param level to query the number of layers of. Must be between 0 and {@link #getLevels}
+ * @return The number of layers of the given level
+ */
public int getDepth(@IntRange(from = 0) int level) {
return nGetDepth(getNativeObject(), level);
}
+ /**
+ * @return the number of mipmap levels of this texture
+ */
public int getLevels() {
return nGetLevels(getNativeObject());
}
+ /**
+ * @return This texture {@link Sampler Sampler} type.
+ */
@NonNull
public Sampler getTarget() {
return Sampler.values()[nGetTarget(getNativeObject())];
}
+ /**
+ * @return This texture's {@link InternalFormat InternalFormat}.
+ */
@NonNull
public InternalFormat getFormat() {
return InternalFormat.values()[nGetInternalFormat(getNativeObject())];
@@ -421,12 +731,65 @@ public class Texture {
// TODO: add a setImage() version that takes an android Bitmap
+ /**
+ * setImage is used to modify the whole content of the texure from a CPU-buffer.
+ *
+ * Texture instance must use {@link Sampler#SAMPLER_2D SAMPLER_2D} or
+ * {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}. If the later is specified
+ * and external textures are supported by the driver implementation,
+ * this method will have no effect, otherwise it will behave as if the
+ * texture was specified with {@link Sampler#SAMPLER_2D SAMPLER_2D}.
+ *
+ * setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer)
+ *
+ * @param engine {@link Engine} this texture is associated to. Must be the
+ * instance passed to {@link Builder#build Builder.build()}.
+ * @param level Level to set the image for. Must be less than {@link #getLevels()}.
+ * @param buffer Client-side buffer containing the image to set.
+ * buffer's {@link Format format} must match that
+ * of {@link #getFormat()}
+ *
+ * @exception BufferOverflowException if the specified parameters would result in reading
+ * outside of buffer.
+ *
+ * @see Builder#sampler(Sampler)
+ * @see PixelBufferDescriptor
+ */
public void setImage(@NonNull Engine engine,
@IntRange(from = 0) int level,
@NonNull PixelBufferDescriptor buffer) {
setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer);
}
+
+ /**
+ * setImage is used to modify a sub-region of the texure from a CPU-buffer.
+ *
+ * Texture instance must use {@link Sampler#SAMPLER_2D SAMPLER_2D} or
+ * {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}. If the later is specified
+ * and external textures are supported by the driver implementation,
+ * this method will have no effect, otherwise it will behave as if the
+ * texture was specified with {@link Sampler#SAMPLER_2D SAMPLER_2D}.buffer's {@link Format format} must match that
+ * of {@link #getFormat()}
+ *
+ * @exception BufferOverflowException if the specified parameters would result in reading
+ * outside of buffer.
+ *
+ * @see Builder#sampler(Sampler)
+ * @see PixelBufferDescriptor
+ */
public void setImage(@NonNull Engine engine,
@IntRange(from = 0) int level,
@IntRange(from = 0) int xoffset, @IntRange(from = 0) int yoffset,
@@ -453,9 +816,33 @@ public class Texture {
}
}
- // note: faceOffsetsInBytes are offsets in byte in the buffer relative to the current position()
- // note: use Texture CubemapFace to index the faceOffsetsInBytes array
- // note: we assume all 6 faces are tightly packed
+ /**
+ * setImage is used to specify all six images of a cubemap level and
+ * follows exactly the OpenGL conventions
+ *
+ * Texture instance must use
+ * {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}.buffer's {@link Format format} must match that
+ * of {@link #getFormat()}
+ * @param faceOffsetsInBytes Offsets in bytes into buffer for all six images.
+ * The offsets are specified in the following order:
+ * +x, -x, +y, -y, +z, -z.
+ *
+ * faceOffsetsInBytes are offsets in byte in the buffer relative
+ * to the current {@link Buffer#position()}. Use {@link CubemapFace} to index the
+ * faceOffsetsInBytes array. All six faces must be tightly packed.buffer.
+ *
+ * @see Builder#sampler(Sampler)
+ * @see PixelBufferDescriptor
+ */
public void setImage(@NonNull Engine engine, @IntRange(from = 0) int level,
@NonNull PixelBufferDescriptor buffer,
@NonNull @Size(min = 6) int[] faceOffsetsInBytes) {
@@ -478,10 +865,60 @@ public class Texture {
}
}
+ /**
+ * Specifies the external image to associate with this Texture.
+ *
+ * Texture instance must use
+ * {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}.
+ *
+ *
+ * @param engine {@link Engine} this texture is associated to. Must be the
+ * instance passed to {@link Builder#build Builder.build()}.
+ * @param eglImage An opaque handle to a platform specific image. Supported types are
+ * eglImageOES on Android and CVPixelBufferRef on iOS.
+ *
+ *
kCVPixelFormatType_32BGRAkCVPixelFormatType_420YpCbCr8BiPlanarFullRange
Texture.
+ *
+ * This Texture instance must use
+ * {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}.
Typically the external image is OS specific, and can be a video or camera frame. + * There are many restrictions when using an external image as a texture, such as:
+ *This Texture instance must not use
+ * {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}, or it has no effect.
This is a utility function that replaces calls to {@link #setImage}.
+ * The provided environment map is processed and all mipmap levels are populated. The
+ * processing is similar to the offline tool cmgen at a lower quality setting.
This function is intended to be used when the environment cannot be processed offline, + * for instance if it's generated at runtime.
+ * + *The source data must obey to some constraints:
+ *The current texture must be a cubemap.
+ * + *The reflections cubemap's {@link InternalFormat internal format} cannot be a compressed format.
+ * + *The reflections cubemap's dimension must be a power-of-two.
+ * + *This operation is computationally intensive, especially with large environments and + * is currently synchronous. Expect about 1ms for a 16 × 16 cubemap.
+ * + * @param engine {@link Engine} this texture is associated to. Must be the + * instance passed to {@link Builder#build Builder.build()}. + * @param buffer Client-side buffer containing the image to set. + *buffer's {@link Format format} and {@link Type type} must match
+ * the constraints above.
+ * @param faceOffsetsInBytes Offsets in bytes into buffer for all six images.
+ * The offsets are specified in the following order:
+ * +x, -x, +y, -y, +z, -z.
+ *
+ * @param options Optional parameter to control user-specified quality and options.
+ *
+ * faceOffsetsInBytes are offsets in byte in the buffer relative
+ * to the current {@link Buffer#position()}. Use {@link CubemapFace} to index the
+ * faceOffsetsInBytes array. All six faces must be tightly packed.
buffer.
+ */
public void generatePrefilterMipmap(@NonNull Engine engine,
@NonNull PixelBufferDescriptor buffer, @NonNull @Size(min = 6) int[] faceOffsetsInBytes,
PrefilterOptions options) {