pub struct Texture { /* private fields */ }
Expand description

A texture, held in GPU memory.

The data can be stored in a variety of formats, as represented by the TextureFormat enum.

Supported File Formats

Images can be decoded from various common file formats via the new and from_encoded constructors. Individual decoders can be enabled or disabled via Cargo feature flags.

FormatCargo featureEnabled by default?
PNGtexture_pngYes
JPEGtexture_jpegYes
GIFtexture_gifYes
BMPtexture_bmpYes
TIFFtexture_tiffNo
TGAtexture_tgaNo
WebPtexture_webpNo
ICOtexture_icoNo
PNMtexture_pnmNo
DDS/DXTtexture_ddsNo

Performance

Creating a texture is quite an expensive operation, as it involves ‘uploading’ the texture data to the GPU. Try to reuse textures, rather than recreating them every frame.

You can clone a texture cheaply, as it is a reference-counted handle to a GPU resource. However, this does mean that modifying a texture (e.g. setting the filter mode) will also affect any clones that exist of it.

Examples

The texture example demonstrates how to draw a simple texture.

Implementations

Creates a new texture from the given file.

The format will be determined based on the file extension.

Errors

Creates a new texture from a slice of pixel data.

This is useful if you wish to create a texture at runtime.

This method requires you to provide enough data to fill the texture. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

Errors
  • TetraError::PlatformError will be returned if the underlying graphics API encounters an error.
  • TetraError::NotEnoughData will be returned if not enough data is provided to fill the texture. This is to prevent the graphics API from trying to read uninitialized memory.

Creates a new texture from a slice of data, encoded in one of Tetra’s supported file formats (except for TGA).

This is useful in combination with include_bytes, as it allows you to include your textures directly in the binary.

The format will be determined based on the ‘magic bytes’ at the beginning of the data. This should be reasonably reliable, but a from_data_with_format function might have to be added later. Note that TGA files do not have recognizable magic bytes, so this function will not recognize them.

Errors

Creates a new texture from an ImageData.

Errors

Draws the texture to the screen (or to a canvas, if one is enabled).

Draws a region of the texture to the screen (or to a canvas, if one is enabled).

Draws a region of the texture by splitting it into nine slices, allowing it to be stretched or squashed without distorting the borders.

Returns the width of the texture.

Returns the height of the texture.

Returns the size of the texture.

Returns the data format of the texture.

Returns the filter mode being used by the texture.

Sets the filter mode that should be used by the texture.

Gets the texture’s data from the GPU.

This can be useful if you need to do some image processing on the CPU, or if you want to output the image data somewhere. This is a fairly slow operation, so avoid doing it too often!

The returned ImageData will have the same format as the texture itself.

Writes pixel data to a specified region of the texture.

The data will be interpreted based on the TextureFormat of the texture.

This method requires you to provide enough data to fill the target rectangle. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you want to overwrite the entire texture, the replace_data method offers a more concise way of doing this.

Errors
  • TetraError::NotEnoughData will be returned if not enough data is provided to fill the target rectangle. This is to prevent the graphics API from trying to read uninitialized memory.
Panics

Panics if any part of the target rectangle is outside the bounds of the texture.

Overwrites the entire texture with new RGBA pixel data.

This method requires you to provide enough data to fill the texture. If you provide too little data, an error will be returned. If you provide too much data, it will be truncated.

If you only want to write to a subsection of the texture, use the set_data method instead.

Errors
  • TetraError::NotEnoughData will be returned if not enough data is provided to fill the texture. This is to prevent the graphics API from trying to read uninitialized memory.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Can be accessed via a sampler2D in your shader.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.