Struct luminance::texture::Texture

pub struct Texture<B, D, P> where
    B: ?Sized + TextureBackend<D, P>,
    D: Dimensionable,
    P: Pixel,  { /* fields omitted */ }

Textures.

Textures allow mainly two use cases:

• Passing data (in the form of images or regular data) to shaders.
• Offscreen rendering.

In the former case, you will want to uplad images to Texture. This can be done with the various upload functions:

• Texture::upload_part
• Texture::upload
• Texture::upload_part_raw
• Texture::upload_raw

In the second case, a Texture can be used as part of a ColorSlot or DepthSlot of a Framebuffer. This allows to create graphics pipeline that will output into the Texture, that you can use in another graphics pipeline later.

Parametricity

Textures have three type parameters:

• B, which is the backend type. It must implement TextureBackend.
• D, the dimension of the texture. It must implement Dimensionable.
• P, the pixel type. It must implement Pixel.

Dimension

The dimension of the texture gives its flavor: 2D, 3D, cubemap, etc. You have access to a bunch of different types here, which all are implementors of the Dimensionable trait.

Pixel format

The internal representation of the Texture will be derived from the P type, which is the Pixel type. Lots of types are available, but you have to know that depending on the use you want to make of the texture, not all types are compatible. For instance, if you access a Texture as part of a ColorSlot of a Framebuffer, the Pixel type must be RenderablePixel. The compiler will always tells you if you are trying to use a pixel type that is not compatible, but you should check the implementors of Pixel, RenderablePixel and DepthPixel before starting using them.

Implementations

impl<B, D, P> Texture<B, D, P> where
    B: ?Sized + TextureBackend<D, P>,
    D: Dimensionable,
    P: Pixel, 

pub fn new<C>(
    ctx: &mut C,
    size: D::Size,
    sampler: Sampler,
    texels: TexelUpload<'_, [P::Encoding]>
) -> Result<Self, TextureError> where
    C: GraphicsContext<Backend = B>, 

Create a new Texture.

size is the desired size of the Texture.

sampler is a Sampler object that will be used when sampling the texture from inside a shader, for instance.

gen_mipmaps determines whether mipmaps should be generated automatically.

texels is a TexelUpload of texels to put into the texture store.

Notes

Feel free to have a look at the documentation of GraphicsContext::new_texture for a simpler interface.

pub fn new_raw<C>(
    ctx: &mut C,
    size: D::Size,
    sampler: Sampler,
    texels: TexelUpload<'_, [P::RawEncoding]>
) -> Result<Self, TextureError> where
    C: GraphicsContext<Backend = B>, 

Create a new Texture with raw texels.

size is the wished size of the Texture.

sampler is a Sampler object that will be used when sampling the texture from inside a shader, for instance.

texels is a TexelUpload of raw texels to put into the texture store.

Notes

Feel free to have a look at the documentation of GraphicsContext::new_texture_raw for a simpler interface.

pub fn mipmaps(&self) -> usize

Return the number of mipmaps.

pub fn size(&self) -> D::Size

Return the size of the texture.

pub fn resize(
    &mut self,
    size: D::Size,
    texels: TexelUpload<'_, [P::Encoding]>
) -> Result<(), TextureError>

Resize the texture by providing a new size and texels by reusing its GPU resources.

This function works similarly to Texture::new but instead of creating a brand new texture, reuses the texture resources on the GPU.

pub fn resize_raw(
    &mut self,
    size: D::Size,
    texels: TexelUpload<'_, [P::RawEncoding]>
) -> Result<(), TextureError>

Resize the texture by providing a new size and raw texels by reusing its GPU resources.

This function works similarly to Texture::new_raw but instead of creating a brand new texture, reuses the texture resources on the GPU.

pub fn upload_part(
    &mut self,
    offset: D::Offset,
    size: D::Size,
    texels: TexelUpload<'_, [P::Encoding]>
) -> Result<(), TextureError>

Upload pixels to a region of the texture described by the rectangle made with size and offset.

pub fn upload(
    &mut self,
    texels: TexelUpload<'_, [P::Encoding]>
) -> Result<(), TextureError>

Upload pixels to the whole texture.

pub fn upload_part_raw(
    &mut self,
    offset: D::Offset,
    size: D::Size,
    texels: TexelUpload<'_, [P::RawEncoding]>
) -> Result<(), TextureError>

Upload raw data to a region of the texture described by the rectangle made with size and offset.

pub fn upload_raw(
    &mut self,
    texels: TexelUpload<'_, [P::RawEncoding]>
) -> Result<(), TextureError>

Upload raw data to the whole texture.

pub fn get_raw_texels(&self) -> Result<Vec<P::RawEncoding>, TextureError> where
    P::RawEncoding: Copy + Default, 

Get a copy of all the pixels from the texture.