From 340f6d721ac663ffff67790460eadd933d14fcd3 Mon Sep 17 00:00:00 2001 From: Mathias Agopian Date: Tue, 1 Oct 2019 17:49:09 -0700 Subject: [PATCH] Texture javadoc --- .../android/filament/IndirectLight.java | 5 +- .../com/google/android/filament/Texture.java | 507 +++++++++++++++++- 2 files changed, 503 insertions(+), 9 deletions(-) diff --git a/android/filament-android/src/main/java/com/google/android/filament/IndirectLight.java b/android/filament-android/src/main/java/com/google/android/filament/IndirectLight.java index 5fa2377909..bd32d17573 100644 --- a/android/filament-android/src/main/java/com/google/android/filament/IndirectLight.java +++ b/android/filament-android/src/main/java/com/google/android/filament/IndirectLight.java @@ -311,10 +311,9 @@ public class IndirectLight { /** * Creates the IndirectLight object and returns a pointer to it. * - * @param engine Reference to the filament::Engine to associate this IndirectLight with. + * @param engine The {@link Engine} to associate this 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 + *

The 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 + * + *

These formats are used to specify a texture's internal storage format.

+ * + *

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
+ *
+ */ public enum InternalFormat { // 8-bits per element R8, R8_SNORM, R8UI, R8I, STENCIL8, @@ -92,6 +216,10 @@ public class Texture { DXT1_RGB, DXT1_RGBA, DXT3_RGBA, DXT5_RGBA } + /** + * Compressed data types for use with {@link PixelBufferDescriptor} + * @see InternalFormat + */ public enum CompressedFormat { // Mandatory in GLES 3.0 and GL 4.3 EAC_R11, EAC_R11_SIGNED, EAC_RG11, EAC_RG11_SIGNED, @@ -103,15 +231,27 @@ public class Texture { DXT1_RGB, DXT1_RGBA, DXT3_RGBA, DXT5_RGBA } + /** + * Cubemap faces + */ public enum CubemapFace { + /** +x face */ POSITIVE_X, + /** -x face */ NEGATIVE_X, + /** +y face */ POSITIVE_Y, + /** -y face */ NEGATIVE_Y, + /** +z face */ POSITIVE_Z, + /** -z face */ NEGATIVE_Z } + /** + * Pixel color format + */ public enum Format { R, R_INTEGER, @@ -128,19 +268,43 @@ public class Texture { ALPHA } + /** + * Pixel data type + */ public enum Type { + /** unsigned byte, 8-bits */ UBYTE, + /** signed byte, 8-bits */ BYTE, + /** unsigned short, 16-bits */ USHORT, + /** signed short, 16-bits */ SHORT, + /** unsigned int, 32-bits */ UINT, + /** signed int, 32-bits */ INT, + /** half-float, 16-bits float with 10 bits mantissa */ HALF, + /** float, 32-bits float, with 24 bits mantissa */ FLOAT, + /** a compessed type */ COMPRESSED, + /** unsigned 5.6 (5.5 for blue) float packed in 32-bits */ UINT_10F_11F_11F_REV } + /** + * A descriptor to an image in main memory, typically used to transfer image data from the CPU + * to the GPU. + *

A 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. + *

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.

+ * @param format texture's {@link InternalFormat internal format}. + * @return This Builder, for chaining calls. + */ @NonNull public Builder format(@NonNull InternalFormat format) { nBuilderFormat(mNativeBuilder, format.ordinal()); @@ -356,6 +626,13 @@ public class Texture { return this; } + /** + * Creates a new 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. + * + *

This 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}.

+ * + * This is equivalent to calling:
+ * + * 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. + * + *

This 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}.

+ * + * @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 xoffset x-offset in texel of the region to modify + * @param yoffset y-offset in texel of the region to modify + * @param width width in texel of the region to modify + * @param height height in texel of the region to modify + * @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, @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 + * + *

This Texture instance must use + * {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}.

+ * + * @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()} + * @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.

+ * + * @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, @NonNull @Size(min = 6) int[] faceOffsetsInBytes) { @@ -478,10 +865,60 @@ public class Texture { } } + /** + * Specifies the external image to associate with this 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:

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

On iOS the following pixel formats are supported:

+ * + * @see Builder#sampler(Sampler) + */ public void setExternalImage(@NonNull Engine engine, long eglImage) { nSetExternalImage(getNativeObject(), engine.getNativeObject(), eglImage); } + /** + * Specifies the external stream to associate with this 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:

+ * + * + * @param engine {@link Engine} this texture is associated to. Must be the + * instance passed to {@link Builder#build Builder.build()}. + * @param stream A {@link Stream} object + * + * @exception IllegalStateException if the sampler type is not + * {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL} + * + * @see Stream + * @see Builder#sampler(Sampler) + * + */ public void setExternalStream(@NonNull Engine engine, @NonNull Stream stream) { long nativeObject = getNativeObject(); long streamNativeObject = stream.getNativeObject(); @@ -492,10 +929,68 @@ public class Texture { nSetExternalStream(nativeObject, engine.getNativeObject(), streamNativeObject); } + /** + * Generates all the mipmap levels automatically. This requires the texture to have a + * color-renderable format. + * + *

This Texture instance must not use + * {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}, or it has no effect.

+ * + * @param engine {@link Engine} this texture is associated to. Must be the + * instance passed to {@link Builder#build Builder.build()}. + */ public void generateMipmaps(@NonNull Engine engine) { nGenerateMipmaps(getNativeObject(), engine.getNativeObject()); } + /** + * Creates a reflection map from an environment map. + * + *

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.

+ * + * @exception BufferOverflowException if the specified parameters would result in reading + * outside of buffer. + */ public void generatePrefilterMipmap(@NonNull Engine engine, @NonNull PixelBufferDescriptor buffer, @NonNull @Size(min = 6) int[] faceOffsetsInBytes, PrefilterOptions options) {