Struct web_glitz::rendering::Framebuffer

pub struct Framebuffer<C, Ds> {
    pub color: C,
    pub depth_stencil: Ds,
    // some fields omitted
}

Represents a set of image memory buffers that serve as the rendering destination for a [RenderPass].

The image buffers allocated in the framebuffer correspond to to the images attached to the [RenderTargetDescription] that was used to define the [RenderPass] (see also [RenderTarget]); specifically, [color] provides handles to the color buffers (if any), and [depth_stencil] provides a handle to the depth-stencil buffer (if any).

Fields

color: C

depth_stencil: Ds

Implementations

impl<C, Ds> Framebuffer<C, Ds> where
    C: BlitColorTarget, 

pub fn blit_color_nearest_command<S>(
    &self,
    region: Region2D,
    source: &S
) -> BlitCommand where
    S: BlitColorCompatible<C>, 

Transfers a rectangle of pixels from the source onto a region of each of the color buffers in the framebuffer, using "nearest" filtering if the source and the region have different sizes.

The image data stored in source must be stored in a format that is BlitColorCompatible with each of the color buffers in the framebuffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used. See [blit_color_linear_command] for a similar operation that uses linear filtering instead.

The source must be a single-sample image. For transferring pixel data from a multisample source image, see [resolve_color_command].

The region of the color buffers is constrained to the area of intersection of all color buffers; a region value of [Region::Fill] will match this area of intersection (note that the origin of a region is in its bottom-left corner). If a region bigger than the intersection is specified with [Region::Area], then any pixels that would be copied outside the region of overlap are discarded for all color buffers (even color buffers that would by themselves have been large enough to contain the region). However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the area of intersection.

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_color_nearest_command(Region2D::Fill, &texture.base_level())
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and texture is a [Texture2D].

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn blit_color_linear_command<S>(
    &self,
    region: Region2D,
    source: &S
) -> BlitCommand where
    S: BlitColorCompatible<C>,
    S::Format: Filterable, 

Transfers a rectangle of pixels from the source onto a region of each of the color buffers in the framebuffer, using "linear" filtering if the source and the region have different sizes.

The image data stored in source must be stored in a format that is BlitColorCompatible with each of the color buffers in the framebuffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "linear" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value is obtained by linear interpolation of the 4 pixels that are nearest to corresponding relative position in the source image. See [blit_color_nearest_command] for a similar operation that uses "nearest" filtering instead.

The source must be a single-sample image. For transferring pixel data from a multisample source image, see [resolve_color_command].

The region of the color buffers is constrained to the area of intersection of all color buffers; a region value of [Region::Fill] will match this area of intersection (note that the origin of a region is in its bottom-left corner). If a region bigger than the intersection is specified with [Region::Area], then any pixels that would be copied outside the region of overlap are discarded for all color buffers (even color buffers that would by themselves have been large enough to contain the region). However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the area of intersection.

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_color_linear_command(Region2D::Fill, &texture.base_level())
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and texture is a [Texture2D].

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_color_command<S>(&self, source: &S) -> ResolveImageCommand where
    S: ResolveColorCompatible<C>, 

Transfers a rectangle of pixels from a multisample source image onto each of the color buffers in the framebuffer.

The image data stored in the source must use a sample format that is identical to (each of) the color buffer(s) in the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_color_nearest_command] and [blit_color_linear_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_color_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample image data.

Panics

Panics if source belongs to a different context than the framebuffer.

impl<C, F> Framebuffer<C, DepthStencilBuffer<F>> where
    F: DepthStencilRenderable, 

pub fn blit_depth_stencil_command<S>(
    &self,
    region: Region2D,
    source: &S
) -> BlitCommand where
    S: BlitSource<Format = F>, 

Transfers a rectangle of both depth and stencil values from the source depth-stencil image onto a region of the depth-stencil buffer in framebuffer, using "nearest" filtering if the source and the region have different sizes.

The depth-stencil data stored in source must be stored in the same format as the storage format format used by the framebuffer's depth-stencil buffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used.

If a region bigger than depth-stencil buffer is specified with [Region::Area], then any pixels that would be copied outside the depth-stencil buffer will be discarded. However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the size of the depth-stencil buffer.

See also [blit_depth_command] and [blit_stencil_command].

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_depth_stencil_command(Region2D::Fill, &renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn blit_depth_command<S>(&self, region: Region2D, source: &S) -> BlitCommand where
    S: BlitSource<Format = F>, 

Transfers a rectangle of only depth values from the source depth-stencil image onto a region of the depth-stencil buffer in framebuffer, using "nearest" filtering if the source and the region have different sizes.

The depth-stencil data stored in source must be stored in the same format as the storage format format used by the framebuffer's depth-stencil buffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used.

If a region bigger than depth-stencil buffer is specified with [Region::Area], then any pixels that would be copied outside the depth-stencil buffer will be discarded. However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the size of the depth-stencil buffer.

See also [blit_depth_stencil_command] and [blit_stencil_command].

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_depth_command(Region2D::Fill, &renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn blit_stencil_command<S>(
    &self,
    region: Region2D,
    source: &S
) -> BlitCommand where
    S: BlitSource<Format = F>, 

Transfers a rectangle of only stencil values from the source depth-stencil image onto a region of the depth-stencil buffer in framebuffer, using "nearest" filtering if the source and the region have different sizes.

The depth-stencil data stored in source must be stored in the same format as the storage format format used by the framebuffer's depth-stencil buffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used.

If a region bigger than depth-stencil buffer is specified with [Region::Area], then any pixels that would be copied outside the depth-stencil buffer will be discarded. However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the size of the depth-stencil buffer.

See also [blit_depth_stencil_command] and [blit_depth_command].

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_stencil_command(Region2D::Fill, &renderbuffer)
});

Here rendering is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_depth_stencil_command<S>(
    &self,
    source: &S
) -> ResolveImageCommand where
    S: ResolveSource<Format = F>, 

Transfers a rectangle of depth-stencil values from a multisample source depth-stencil image onto the depth-stencil buffer of the framebuffer.

The image data stored in the source must use a sample format that is identical to the depth-stencil format used by the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_depth_stencil_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_depth_stencil_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample depth-stencil data.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_depth_command<S>(&self, source: &S) -> ResolveImageCommand where
    S: ResolveSource<Format = F>, 

Transfers a rectangle of only depth values from a multisample source depth-stencil image onto the depth-stencil buffer of the framebuffer.

The image data stored in the source must use a sample format that is identical to the depth-stencil format used by the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_depth_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_depth_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample depth-stencil data.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_stencil_command<S>(&self, source: &S) -> ResolveImageCommand where
    S: ResolveSource<Format = F>, 

Transfers a rectangle of only stencil values from a multisample source depth-stencil image onto the depth-stencil buffer of the framebuffer.

The image data stored in the source must use a sample format that is identical to the depth-stencil format used by the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_stencil_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_stencil_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample depth-stencil data.

Panics

Panics if source belongs to a different context than the framebuffer.

impl<C, F> Framebuffer<C, DepthBuffer<F>> where
    F: DepthRenderable, 

pub fn blit_depth_command<S>(&self, region: Region2D, source: &S) -> BlitCommand where
    S: BlitSource<Format = F>, 

Transfers a rectangle of depth values from the source depth image onto a region of the depth buffer in framebuffer, using "nearest" filtering if the source and the region have different sizes.

The depth data stored in source must be stored in the same format as the storage format format used by the framebuffer's depth buffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used.

If a region bigger than depth buffer is specified with [Region::Area], then any pixels that would be copied outside the depth buffer will be discarded. However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the size of the depth buffer.

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_depth_command(Region2D::Fill, &renderbuffer)
});

Here rendering is a [RenderTargetDescription] and renderbuffer is a Renderbuffer.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_depth_command<S>(&self, source: &S) -> ResolveImageCommand where
    S: ResolveSource<Format = F>, 

Transfers a rectangle of depth values from a multisample source depth image onto the depth buffer of the framebuffer.

The image data stored in the source must use a sample format that is identical to the depth format used by the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_depth_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_depth_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample depth data.

Panics

Panics if source belongs to a different context than the framebuffer.

impl<C, F> Framebuffer<C, StencilBuffer<F>> where
    F: StencilRenderable, 

pub fn blit_stencil_command<S>(
    &self,
    region: Region2D,
    source: &S
) -> BlitCommand where
    S: BlitSource<Format = F>, 

Transfers a rectangle of stencil values from the source depth image onto a region of the stencil buffer in framebuffer, using "nearest" filtering if the source and the region have different sizes.

The stencil data stored in source must be stored in the same format as the storage format format used by the framebuffer's stencil buffer. If the source image has a different size (width or height) than the region, then the source will be scaled to match the size of the region. If scaling is required, then "nearest" filtering is used to obtain pixel values for the resized image, where for each pixel value in the resized image, the value of the pixel that is at the nearest corresponding relative position is used.

If a region bigger than stencil buffer is specified with [Region::Area], then any pixels that would be copied outside the stencil buffer will be discarded. However, the amount of scaling that is applied is based solely on the size of the region, it is not affected by the size of the stencil buffer.

Example

use web_glitz::image::Region2D;

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.blit_stencil_command(Region2D::Fill, &renderbuffer)
});

Here rendering is a [RenderTargetDescription] and renderbuffer is a Renderbuffer.

Panics

Panics if source belongs to a different context than the framebuffer.

pub fn resolve_stencil_command<S>(&self, source: &S) -> ResolveImageCommand where
    S: ResolveSource<Format = F>, 

Transfers a rectangle of stencil values from a multisample source stencil image onto the stencil buffer of the framebuffer.

The image data stored in the source must use a sample format that is identical to the stencil format used by the framebuffer. No scaling is applied if the source image is a different size (width or height) than the framebuffer; the source image is transferred into the "bottom-left" of the framebuffer, any excess is discarded.

For pixel transfer operations from single-sample source images, see [blit_stencil_command].

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.resolve_stencil_command(&renderbuffer)
});

Here render_target is a [RenderTarget] or [DefaultRenderTarget] and renderbuffer is a Renderbuffer containing multisample stencil data.

Panics

Panics if source belongs to a different context than the framebuffer.

Methods from Deref<Target = GraphicsPipelineTarget>

pub fn pipeline_task<P, V, R, Tf, F, T>(
    &self,
    pipeline: &P,
    f: F
) -> PipelineTask<T> where
    P: GraphicsPipelineState<V, R, Tf>,
    F: Fn(ActiveGraphicsPipeline<'_, V, R, Tf>) -> T,
    T: GpuTask<PipelineTaskContext>, 

Creates a pipeline task using the given graphics_pipeline.

The second parameter f must be a function that returns the task that is to be executed while the graphics_pipeline is bound as the active graphics pipeline. This function will receive a reference to this ActiveGraphicsPipeline which may be used to encode draw commands (see [ActiveGraphicsPipeline::draw_command]). The task returned by the function typically consists of 1 ore more draw commands that were created in this way. The current framebuffer serves as the output target for the graphics_pipeline (your draw commands may modify the current framebuffer).

Example

let render_pass = render_target.create_render_pass(|framebuffer| {
    framebuffer.pipeline_task(&graphics_pipeline, |active_pipeline| {
        active_pipeline.task_builder()
            .bind_vertex_buffers(&vertex_buffer)
            .bind_resources(&resources)
            .draw(16, 1)
            .finish()
    })
});

In this example, context is a [RenderingContext]; render_target is a [RenderTarget], see also [DefaultRenderTarget] and [RenderTarget]; graphics_pipeline is a GraphicsPipeline, see GraphicsPipeline for details; vertex_buffer is a [Buffer] holding a [Vertex] type, see [Buffer], [Vertex] for details; resources is a resource [BindGroup], see [BindGroup] for details.

Panics

Panics if the graphics_pipeline belongs to a different context than the framebuffer for which this pipeline task is being created.

Panics if the task returned by f contains commands that were constructed for a different pipeline task context.

Trait Implementations

impl<C, Ds> Deref for Framebuffer<C, Ds>

type Target = GraphicsPipelineTarget

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.