Texture javadoc
This commit is contained in:
committed by
Mathias Agopian
parent
489f3ff3c9
commit
340f6d721a
+2
-3
@@ -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 <code>IndirectLight</code> with.
|
||||
*
|
||||
* @return pointer to the newly created object or nullptr if exceptions are disabled and
|
||||
* an error occurred.
|
||||
* @return A newly created <code>IndirectLight</code>
|
||||
*
|
||||
* @exception IllegalStateException if a parameter to a builder function was invalid.
|
||||
*/
|
||||
|
||||
@@ -29,6 +29,47 @@ import java.nio.ByteBuffer;
|
||||
|
||||
import static com.google.android.filament.Texture.Type.COMPRESSED;
|
||||
|
||||
/**
|
||||
* Texture
|
||||
* <p>The <code>Texture</code> class supports:</p>
|
||||
* <ul>
|
||||
* <li>2D textures</li>
|
||||
* <li>3D textures</li>
|
||||
* <li>Cube maps</li>
|
||||
* <li>mip mapping</li>
|
||||
* </ul>
|
||||
*
|
||||
*
|
||||
* <h1>Usage example</h1>
|
||||
*
|
||||
* A <code>Texture</code> object is created using the {@link Texture.Builder} and destroyed by
|
||||
* calling {@link Engine#destroyTexture}. They're bound using {@link MaterialInstance#setParameter}.
|
||||
*
|
||||
* <pre>
|
||||
* 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());
|
||||
* </pre>
|
||||
*
|
||||
* @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
|
||||
*
|
||||
* <p>These formats are used to specify a texture's internal storage format.</p>
|
||||
*
|
||||
* <h1>Enumerants syntax format</h1>
|
||||
*
|
||||
* <code>[components][size][type]</code>
|
||||
* <br><code>components</code> : List of stored components by this format
|
||||
* <br><code>size</code> : Size in bit of each component
|
||||
* <br><code>type</code> : Type this format is stored as
|
||||
*
|
||||
* <center>
|
||||
* <table border="1">
|
||||
* <tr><th> Name </th><th> Component </th></tr>
|
||||
* <tr><td> R </td><td> Linear Red </td></tr>
|
||||
* <tr><td> RG </td><td> Linear Red, Green </td></tr>
|
||||
* <tr><td> RGB </td><td> Linear Red, Green, Blue </td></tr>
|
||||
* <tr><td> RGBA </td><td> Linear Red, Green Blue, Alpha </td></tr>
|
||||
* <tr><td> SRGB </td><td> sRGB encoded Red, Green, Blue </td></tr>
|
||||
* <tr><td> DEPTH </td><td> Depth </td></tr>
|
||||
* <tr><td> STENCIL </td><td> Stencil </td></tr>
|
||||
* </table>
|
||||
* </center>
|
||||
* <br>
|
||||
*
|
||||
* <center>
|
||||
* <table border="1">
|
||||
* <tr><th> Name </th><th> Type </th></tr>
|
||||
* <tr><td> (none) </td><td> Unsigned Normalized Integer [0, 1] </th></tr>
|
||||
* <tr><td> _SNORM </td><td> Signed Normalized Integer [-1, 1] </td></tr>
|
||||
* <tr><td> UI </td><td> Unsigned Integer [0, 2<sup>size</sup>] </td></tr>
|
||||
* <tr><td> I </td><td> Signed Integer [-2<sup>size-1</sup>, 2<sup>size-1</sup>-1] </td></tr>
|
||||
* <tr><td> F </td><td> Floating-point </td></tr>
|
||||
* </table>
|
||||
* </center>
|
||||
* <br>
|
||||
*
|
||||
* <h1>Special color formats</h1>
|
||||
*
|
||||
* There are a few special color formats that don't follow the convention above:
|
||||
*
|
||||
* <center>
|
||||
* <table border="1">
|
||||
* <tr><th> Name </th><th> Format </th></tr>
|
||||
* <tr><td> RGB565 </td><td> 5-bits for R and B, 6-bits for G. </td></tr>
|
||||
* <tr><td> RGB5_A1 </td><td> 5-bits for R, G and B, 1-bit for A. </td></tr>
|
||||
* <tr><td> RGB10_A2 </td><td> 10-bits for R, G and B, 2-bits for A. </td></tr>
|
||||
* <tr><td> RGB9_E5 </td><td> <b>Unsigned</b> floating point. 9-bits mantissa for RGB, 5-bits shared exponent </td></tr>
|
||||
* <tr><td> R11F_G11F_B10F </td><td> <b>Unsigned</b> floating point. 6-bits mantissa, for R and G, 5-bits for B. 5-bits exponent. </td></tr>
|
||||
* <tr><td> SRGB8_A8 </td><td> sRGB 8-bits with linear 8-bits alpha. </td></tr>
|
||||
* <tr><td> DEPTH24_STENCIL8 </td><td> 24-bits unsigned normalized integer depth, 8-bits stencil. </td></tr>
|
||||
* </table>
|
||||
* </center>
|
||||
* <br>
|
||||
*
|
||||
* <h1>Compressed texture formats</h1>
|
||||
*
|
||||
* Many compressed texture formats are supported as well, which include (but are not limited to)
|
||||
* the following list:
|
||||
*
|
||||
* <center>
|
||||
* <table border="1">
|
||||
* <tr><th> Name </th><th> Format </th></tr>
|
||||
* <tr><td> EAC_R11 </td><td> Compresses R11UI </td></tr>
|
||||
* <tr><td> EAC_R11_SIGNED </td><td> Compresses R11I </td></tr>
|
||||
* <tr><td> EAC_RG11 </td><td> Compresses RG11UI </td></tr>
|
||||
* <tr><td> EAC_RG11_SIGNED </td><td> Compresses RG11I </td></tr>
|
||||
* <tr><td> ETC2_RGB8 </td><td> Compresses RGB8 </td></tr>
|
||||
* <tr><td> ETC2_SRGB8 </td><td> compresses SRGB8 </td></tr>
|
||||
* <tr><td> ETC2_EAC_RGBA8 </td><td> Compresses RGBA8 </td></tr>
|
||||
* <tr><td> ETC2_EAC_SRGBA8 </td><td> Compresses SRGB8_A8 </td></tr>
|
||||
* <tr><td> ETC2_RGB8_A1 </td><td> Compresses RGB8 with 1-bit alpha </td></tr>
|
||||
* <tr><td> ETC2_SRGB8_A1 </td><td> Compresses sRGB8 with 1-bit alpha </td></tr>
|
||||
* </table>
|
||||
* </center>
|
||||
*/
|
||||
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.
|
||||
* <p>A <code>PixelBufferDescriptor</code> owns the memory buffer it references,
|
||||
* therefore <code>PixelBufferDescriptor</code> cannot be copied, but can be moved.</p>
|
||||
*
|
||||
* <code>PixelBufferDescriptor</code> 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 <code>PixelBufferDescriptor</code>
|
||||
*
|
||||
* @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 <code>handler</code> when <code>storage</code> 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 <code>PixelBufferDescriptor</code> 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 <code>PixelBufferDescriptor</code> 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 <code>PixelBufferDescriptor</code> 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 <code>handler</code> when <code>storage</code> 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 <code>true</code> if this format is supported for texturing.
|
||||
*/
|
||||
public static boolean isTextureFormatSupported(@NonNull Engine engine,
|
||||
@NonNull InternalFormat format) {
|
||||
return nIsTextureFormatSupported(engine.getNativeObject(), format.ordinal());
|
||||
}
|
||||
|
||||
/**
|
||||
* Use <code>Builder</code> to construct a <code>Texture</code> object instance.
|
||||
*/
|
||||
public static class Builder {
|
||||
@SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
|
||||
// Keep to finalize native resources
|
||||
private final BuilderFinalizer mFinalizer;
|
||||
private final long mNativeBuilder;
|
||||
|
||||
/**
|
||||
* Use <code>Builder</code> to construct a <code>Texture</code> 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 <code>floor(log<sub>2</sub>(max(width, height))) + 1</code>. 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.
|
||||
* <p>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.</p>
|
||||
* @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 <code>Texture</code> instance.
|
||||
* @param engine The {@link Engine} to associate this <code>Texture</code> with.
|
||||
* @return A newly created <code>Texture</code>
|
||||
* @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 <code>UPLOADABLE</code> and <code>SAMPLEABLE</code>*/
|
||||
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
|
||||
|
||||
/**
|
||||
* <code>setImage</code> is used to modify the whole content of the texure from a CPU-buffer.
|
||||
*
|
||||
* <p>This <code>Texture</code> 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}.</p>
|
||||
*
|
||||
* This is equivalent to calling: <br>
|
||||
*
|
||||
* <code>setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer)</code>
|
||||
*
|
||||
* @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.
|
||||
* <code>buffer</code>'s {@link Format format} must match that
|
||||
* of {@link #getFormat()}
|
||||
*
|
||||
* @exception BufferOverflowException if the specified parameters would result in reading
|
||||
* outside of <code>buffer</code>.
|
||||
*
|
||||
* @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);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* <code>setImage</code> is used to modify a sub-region of the texure from a CPU-buffer.
|
||||
*
|
||||
* <p>This <code>Texture</code> 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}.</p>
|
||||
*
|
||||
* @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.
|
||||
* <code>buffer</code>'s {@link Format format} must match that
|
||||
* of {@link #getFormat()}
|
||||
*
|
||||
* @exception BufferOverflowException if the specified parameters would result in reading
|
||||
* outside of <code>buffer</code>.
|
||||
*
|
||||
* @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
|
||||
/**
|
||||
* <code>setImage</code> is used to specify all six images of a cubemap level and
|
||||
* follows exactly the OpenGL conventions
|
||||
*
|
||||
* <p>This <code>Texture</code> instance must use
|
||||
* {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}.</p>
|
||||
*
|
||||
* @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.
|
||||
* <code>buffer</code>'s {@link Format format} must match that
|
||||
* of {@link #getFormat()}
|
||||
* @param faceOffsetsInBytes Offsets in bytes into <code>buffer</code> for all six images.
|
||||
* The offsets are specified in the following order:
|
||||
* +x, -x, +y, -y, +z, -z.
|
||||
*
|
||||
* <p><code>faceOffsetsInBytes</code> are offsets in byte in the <code>buffer</code> relative
|
||||
* to the current {@link Buffer#position()}. Use {@link CubemapFace} to index the
|
||||
* <code>faceOffsetsInBytes</code> array. All six faces must be tightly packed.</p>
|
||||
*
|
||||
* @exception BufferOverflowException if the specified parameters would result in reading
|
||||
* outside of <code>buffer</code>.
|
||||
*
|
||||
* @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 <code>Texture</code>.
|
||||
*
|
||||
* <p>This <code>Texture</code> instance must use
|
||||
* {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}.</p>
|
||||
* <p>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:</p>
|
||||
* <ul>
|
||||
* <li> only the level of detail (LOD) 0 can be specified</li>
|
||||
* <li> only {@link TextureSampler.MagFilter#NEAREST NEAREST} or
|
||||
* {@link TextureSampler.MagFilter#LINEAR LINEAR} filtering is supported</li>
|
||||
* <li> the size and format of the texture is defined by the external image</li>
|
||||
* </ul>
|
||||
*
|
||||
* @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
|
||||
* <code>eglImageOES</code> on Android and <code>CVPixelBufferRef</code> on iOS.
|
||||
* <p>On iOS the following pixel formats are supported: <ul>
|
||||
* <li><code>kCVPixelFormatType_32BGRA</code></li>
|
||||
* <li><code>kCVPixelFormatType_420YpCbCr8BiPlanarFullRange</code></li>
|
||||
* </ul></p>
|
||||
*
|
||||
* @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 <code>Texture</code>.
|
||||
*
|
||||
* <p>This <code>Texture</code> instance must use
|
||||
* {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}.</p>
|
||||
* <p>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:</p>
|
||||
* <ul>
|
||||
* <li> only the level of detail (LOD) 0 can be specified</li>
|
||||
* <li> only {@link TextureSampler.MagFilter#NEAREST NEAREST} or
|
||||
* {@link TextureSampler.MagFilter#LINEAR LINEAR} filtering is supported</li>
|
||||
* <li> the size and format of the texture is defined by the external image</li>
|
||||
* </ul>
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* <p>This <code>Texture</code> instance must <b>not</b> use
|
||||
* {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}, or it has no effect.</p>
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* <p>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 <code>cmgen</code> at a lower quality setting.</p>
|
||||
*
|
||||
* <p>This function is intended to be used when the environment cannot be processed offline,
|
||||
* for instance if it's generated at runtime.</p>
|
||||
*
|
||||
* <p>The source data must obey to some constraints:</p>
|
||||
* <ul>
|
||||
* <li>the data {@link Format format} must be {@link Format#RGB}</li>
|
||||
* <li>the data {@link Type type} must be one of
|
||||
* <ul>
|
||||
* <li>{@link Type#FLOAT}</li>
|
||||
* <li>{@link Type#HALF}</li>
|
||||
* </ul>
|
||||
* </li>
|
||||
* </ul>
|
||||
*
|
||||
* <p>The current texture must be a cubemap.</p>
|
||||
*
|
||||
* <p>The reflections cubemap's {@link InternalFormat internal format} cannot be a compressed format.</p>
|
||||
*
|
||||
* <p>The reflections cubemap's dimension must be a power-of-two.</p>
|
||||
*
|
||||
* <p>This operation is computationally intensive, especially with large environments and
|
||||
* is currently <b>synchronous</b>. Expect about 1ms for a 16 × 16 cubemap.</p>
|
||||
*
|
||||
* @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.
|
||||
* <code>buffer</code>'s {@link Format format} and {@link Type type} must match
|
||||
* the constraints above.
|
||||
* @param faceOffsetsInBytes Offsets in bytes into <code>buffer</code> 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.
|
||||
*
|
||||
* <p><code>faceOffsetsInBytes</code> are offsets in byte in the <code>buffer</code> relative
|
||||
* to the current {@link Buffer#position()}. Use {@link CubemapFace} to index the
|
||||
* <code>faceOffsetsInBytes</code> array. All six faces must be tightly packed.</p>
|
||||
*
|
||||
* @exception BufferOverflowException if the specified parameters would result in reading
|
||||
* outside of <code>buffer</code>.
|
||||
*/
|
||||
public void generatePrefilterMipmap(@NonNull Engine engine,
|
||||
@NonNull PixelBufferDescriptor buffer, @NonNull @Size(min = 6) int[] faceOffsetsInBytes,
|
||||
PrefilterOptions options) {
|
||||
|
||||
Reference in New Issue
Block a user