Package com.google.android.filament

Class Texture

java.lang.Object

com.google.android.filament.Texture

public class Texture
extends java.lang.Object

Texture

The Texture class supports:

• 2D textures
• 3D textures
• Cube maps
• mip mapping

Usage example

A Texture object is created using the Texture.Builder and destroyed by calling Engine.destroyTexture(com.google.android.filament.Texture). They're bound using MaterialInstance.setParameter(java.lang.String, boolean).

  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 Also:

setImage(com.google.android.filament.Engine, int, com.google.android.filament.Texture.PixelBufferDescriptor), Texture.PixelBufferDescriptor, MaterialInstance.setParameter(String, Texture, TextureSampler)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Texture.Builder	Use Builder to construct a Texture object instance.
static class	Texture.CompressedFormat	Compressed data types for use with Texture.PixelBufferDescriptor
static class	Texture.CubemapFace	Cubemap faces
static class	Texture.Format	Pixel color format
static class	Texture.InternalFormat	Internal texel formats
static class	Texture.PixelBufferDescriptor	A descriptor to an image in main memory, typically used to transfer image data from the CPU to the GPU.
static class	Texture.PrefilterOptions	Options of generatePrefilterMipmap(com.google.android.filament.Engine, com.google.android.filament.Texture.PixelBufferDescriptor, int[], com.google.android.filament.Texture.PrefilterOptions)
static class	Texture.Sampler	Type of sampler
static class	Texture.Swizzle	Texture swizzling channels
static class	Texture.Type	Pixel data type
static class	Texture.Usage	A bitmask to specify how the texture will be used.

Field Summary

Fields

Modifier and Type	Field	Description
static int	BASE_LEVEL

Constructor Summary

Constructors

Constructor	Description
Texture(long nativeTexture)

Method Summary

Modifier and Type	Method	Description
void	generateMipmaps(Engine engine)	Generates all the mipmap levels automatically.
void	generatePrefilterMipmap(Engine engine, Texture.PixelBufferDescriptor buffer, int[] faceOffsetsInBytes, Texture.PrefilterOptions options)	Creates a reflection map from an environment map.
int	getDepth(int level)	Queries the number of layers of given level of this texture has.
Texture.InternalFormat	getFormat()
int	getHeight(int level)	Queries the height of a given level of this texture.
int	getLevels()
long	getNativeObject()
Texture.Sampler	getTarget()
int	getWidth(int level)	Queries the width of a given level of this texture.
static boolean	isTextureFormatSupported(Engine engine, Texture.InternalFormat format)	Checks whether a given format is supported for texturing in this Engine.
static boolean	isTextureSwizzleSupported(Engine engine)	Checks whether texture swizzling is supported in this Engine.
void	setExternalImage(Engine engine, long eglImage)	Specifies the external image to associate with this Texture.
void	setExternalStream(Engine engine, Stream stream)	Specifies the external stream to associate with this Texture.
void	setImage(Engine engine, int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth, Texture.PixelBufferDescriptor buffer)	setImage is used to modify a sub-region of the 3D texture or 2D texture array from a CPU-buffer.
void	setImage(Engine engine, int level, int xoffset, int yoffset, int width, int height, Texture.PixelBufferDescriptor buffer)	setImage is used to modify a sub-region of the texture from a CPU-buffer.
void	setImage(Engine engine, int level, Texture.PixelBufferDescriptor buffer)	setImage is used to modify the whole content of the texure from a CPU-buffer.
void	setImage(Engine engine, int level, Texture.PixelBufferDescriptor buffer, int[] faceOffsetsInBytes)	setImage is used to specify all six images of a cubemap level and follows exactly the OpenGL conventions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BASE_LEVEL

public static final int BASE_LEVEL

See Also:

Constant Field Values

Constructor Detail

Texture

public Texture(long nativeTexture)

Method Detail

isTextureFormatSupported

public static boolean isTextureFormatSupported(@NonNull
                                               Engine engine,
                                               @NonNull
                                               Texture.InternalFormat format)

Checks whether a given format is supported for texturing in this Engine. This depends on the selected backend.

Parameters:

engine - Engine to test the InternalFormat against

format - format to check

Returns:

true if this format is supported for texturing.

isTextureSwizzleSupported

public static boolean isTextureSwizzleSupported(@NonNull
                                                Engine engine)

Checks whether texture swizzling is supported in this Engine. This depends on the selected backend.

Parameters:

engine - Engine

Returns:

true if texture swizzling.

getWidth

public int getWidth(@IntRange(from=0L)
                    int level)

Queries the width of a given level of this texture.

Parameters:

level - to query the with of. Must be between 0 and getLevels()

Returns:

The width in texel of the given level

getHeight

public int getHeight(@IntRange(from=0L)
                     int level)

Queries the height of a given level of this texture.

Parameters:

level - to query the height of. Must be between 0 and getLevels()

Returns:

The height in texel of the given level

getDepth

public int getDepth(@IntRange(from=0L)
                    int level)

Queries the number of layers of given level of this texture has.

Parameters:

level - to query the number of layers of. Must be between 0 and getLevels()

Returns:

The number of layers of the given level

getLevels

public int getLevels()

Returns:

the number of mipmap levels of this texture

getTarget

@NonNull
public Texture.Sampler getTarget()

Returns:

This texture Sampler type.

getFormat

@NonNull
public Texture.InternalFormat getFormat()

Returns:

This texture's InternalFormat.

setImage

public void setImage(@NonNull
                     Engine engine,
                     @IntRange(from=0L)
                     int level,
                     @NonNull
                     Texture.PixelBufferDescriptor buffer)

setImage is used to modify the whole content of the texure from a CPU-buffer.

This Texture instance must use SAMPLER_2D or 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 SAMPLER_2D.

This is equivalent to calling:
setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer)

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

level - Level to set the image for. Must be less than getLevels().

buffer - Client-side buffer containing the image to set. buffer's format must match that of getFormat()

Throws:

java.nio.BufferOverflowException - if the specified parameters would result in reading outside of buffer.

See Also:

Texture.Builder.sampler(com.google.android.filament.Texture.Sampler), Texture.PixelBufferDescriptor

setImage

public void setImage(@NonNull
                     Engine engine,
                     @IntRange(from=0L)
                     int level,
                     @IntRange(from=0L)
                     int xoffset,
                     @IntRange(from=0L)
                     int yoffset,
                     @IntRange(from=0L)
                     int width,
                     @IntRange(from=0L)
                     int height,
                     @NonNull
                     Texture.PixelBufferDescriptor buffer)

setImage is used to modify a sub-region of the texture from a CPU-buffer.

This Texture instance must use SAMPLER_2D or 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 SAMPLER_2D.

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

level - Level to set the image for. Must be less than getLevels().

xoffset - x-offset in texel of the region to modify

yoffset - y-offset in texel of the region to modify

width - width in texel of the region to modify

height - height in texel of the region to modify

buffer - Client-side buffer containing the image to set. buffer's format must match that of getFormat()

Throws:

java.nio.BufferOverflowException - if the specified parameters would result in reading outside of buffer.

See Also:

Texture.Builder.sampler(com.google.android.filament.Texture.Sampler), Texture.PixelBufferDescriptor

setImage

public void setImage(@NonNull
                     Engine engine,
                     @IntRange(from=0L)
                     int level,
                     @IntRange(from=0L)
                     int xoffset,
                     @IntRange(from=0L)
                     int yoffset,
                     @IntRange(from=0L)
                     int zoffset,
                     @IntRange(from=0L)
                     int width,
                     @IntRange(from=0L)
                     int height,
                     @IntRange(from=0L)
                     int depth,
                     @NonNull
                     Texture.PixelBufferDescriptor buffer)

setImage is used to modify a sub-region of the 3D texture or 2D texture array from a CPU-buffer.

This Texture instance must use SAMPLER_2D_ARRAY or SAMPLER_3D.

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

level - Level to set the image for. Must be less than getLevels().

xoffset - x-offset in texel of the region to modify

yoffset - y-offset in texel of the region to modify

zoffset - z-offset in texel of the region to modify

width - width in texel of the region to modify

height - height in texel of the region to modify

depth - depth in texel or index of the region to modify

buffer - Client-side buffer containing the image to set. buffer's format must match that of getFormat()

Throws:

java.nio.BufferOverflowException - if the specified parameters would result in reading outside of buffer.

See Also:

Texture.Builder.sampler(com.google.android.filament.Texture.Sampler), Texture.PixelBufferDescriptor

setImage

public void setImage(@NonNull
                     Engine engine,
                     @IntRange(from=0L)
                     int level,
                     @NonNull
                     Texture.PixelBufferDescriptor buffer,
                     @NonNull @Size(min=6L)
                     int[] faceOffsetsInBytes)

setImage is used to specify all six images of a cubemap level and follows exactly the OpenGL conventions

This Texture instance must use SAMPLER_CUBEMAP.

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

level - Level to set the image for. Must be less than getLevels().

buffer - Client-side buffer containing the image to set. buffer's format must match that of getFormat()

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 Buffer.position(). Use Texture.CubemapFace to index the faceOffsetsInBytes array. All six faces must be tightly packed.

Throws:

java.nio.BufferOverflowException - if the specified parameters would result in reading outside of buffer.

See Also:

Texture.Builder.sampler(com.google.android.filament.Texture.Sampler), Texture.PixelBufferDescriptor

setExternalImage

public void setExternalImage(@NonNull
                             Engine engine,
                             long eglImage)

Specifies the external image to associate with this Texture.

This Texture instance must use 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:

• only the level of detail (LOD) 0 can be specified
• only NEAREST or LINEAR filtering is supported
• the size and format of the texture is defined by the external image

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

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:

• kCVPixelFormatType_32BGRA
• kCVPixelFormatType_420YpCbCr8BiPlanarFullRange

See Also:

Texture.Builder.sampler(com.google.android.filament.Texture.Sampler)

setExternalStream

public void setExternalStream(@NonNull
                              Engine engine,
                              @NonNull
                              Stream stream)

Specifies the external stream to associate with this Texture.

This Texture instance must use 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:

• only the level of detail (LOD) 0 can be specified
• only NEAREST or LINEAR filtering is supported
• the size and format of the texture is defined by the external image

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

stream - A Stream object

Throws:

java.lang.IllegalStateException - if the sampler type is not SAMPLER_EXTERNAL

See Also:

Stream, Texture.Builder.sampler(com.google.android.filament.Texture.Sampler)

generateMipmaps

public void generateMipmaps(@NonNull
                            Engine engine)

Generates all the mipmap levels automatically. This requires the texture to have a color-renderable format.

This Texture instance must not use SAMPLER_CUBEMAP, or it has no effect.

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

generatePrefilterMipmap

public void generatePrefilterMipmap(@NonNull
                                    Engine engine,
                                    @NonNull
                                    Texture.PixelBufferDescriptor buffer,
                                    @NonNull @Size(min=6L)
                                    int[] faceOffsetsInBytes,
                                    Texture.PrefilterOptions options)

Creates a reflection map from an environment map.

This is a utility function that replaces calls to setImage(com.google.android.filament.Engine, int, com.google.android.filament.Texture.PixelBufferDescriptor). 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 data format must be Texture.Format.RGB
• the data type must be one of
  • Texture.Type.FLOAT
  • Texture.Type.HALF

The current texture must be a cubemap.

The reflections cubemap's 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.

Parameters:

engine - Engine this texture is associated to. Must be the instance passed to Builder.build().

buffer - Client-side buffer containing the image to set. buffer's format and type must match the constraints above.

faceOffsetsInBytes - Offsets in bytes into buffer for all six images. The offsets are specified in the following order: +x, -x, +y, -y, +z, -z.

options - Optional parameter to control user-specified quality and options.

faceOffsetsInBytes are offsets in byte in the buffer relative to the current Buffer.position(). Use Texture.CubemapFace to index the faceOffsetsInBytes array. All six faces must be tightly packed.

Throws:

java.nio.BufferOverflowException - if the specified parameters would result in reading outside of buffer.

getNativeObject

public long getNativeObject()