Struct tetra::graphics::BlendState

pub struct BlendState {
    pub color_operation: BlendOperation,
    pub color_src: BlendFactor,
    pub color_dst: BlendFactor,
    pub alpha_operation: BlendOperation,
    pub alpha_src: BlendFactor,
    pub alpha_dst: BlendFactor,
}

Defines how colors should be blended when drawing to the screen.

The blend state can be changed by calling set_blend_state or reset_blend_state.

There are constructors for the most common configurations, but if you know what you’re doing, you can set each part of the blend config manually via the fields on this struct.

What is blending?

Blending is how we determine the result of drawing one color on top of another one. This is what lets you (among other things) draw semi-transparent objects and see their colors mix together!

There are two steps to blending:

• First, the source and destination colors are factored (or in simpler terms, multiplied) by values. This determines how much the source and destination contribute to the final output. The RGB and alpha components of each color can have different factors applied.
• Then, an operation (aka a function or an equation) is performed on the two factored values. Again, the RGB and alpha components can be combined via two different operations.

This is all quite abstract, so here’s an example of how the default alpha blending BlendState works:

• We try to draw the color (1.0, 0.2, 0.2, 0.5) on top of the color (0.2, 1.0, 0.2, 1.0), which requires a blend to take place.
• The RGB components of the source color are factored by the alpha of the source color, which gives (0.5, 0.1, 0.1, 0.5). The alpha component is left as it is.
• The entire destination color is factored by the alpha of the source color, which gives (0.25, 0.05, 0.05, 0.5).
• The ‘add’ operation is applied to the two colors, giving us (0.75, 0.15, 0.15, 1.0) as the final color.

Notice that the resulting color is fully opaque and is made up of 50% of the source RGB, and 50% of the destination RGB - which is exactly what we’d expect when we’re drawing something that’s 50% transparent!

For a more in-depth explanation of blending, see this page on Learn OpenGL.

Fields

color_operation: BlendOperation

The operation that should be applied to the RGB components of the source and destination colors.

color_src: BlendFactor

The factor that should be applied to the RGB components of the source color.

color_dst: BlendFactor

The factor that should be applied to the RGB components of the destination color.

alpha_operation: BlendOperation

The operation that should be applied to the alpha components of the source and destination colors.

alpha_src: BlendFactor

The factor that should be applied to the alpha component of the source color.

alpha_dst: BlendFactor

The factor that should be applied to the alpha component of the destination color.

Implementations

impl BlendState

pub const fn alpha(premultiplied: bool) -> BlendState

The alpha of the drawn content will determine its opacity.

If premultiplied is false, the RGB components of the color will be multiplied by the alpha component before blending with the target. If it is true, this step will be skipped, and you will need to do it yourself (e.g. in your own code, or your asset pipeline).

For more information on premultiplied alpha, and why you might want to use it, see these blog posts.

pub const fn add(premultiplied: bool) -> BlendState

The pixel colors of the drawn content will be added to the pixel colors already in the target.

The target’s alpha will not be affected.

If premultiplied is false, the RGB components of the color will be multiplied by the alpha component before blending with the target. If it is true, this step will be skipped, and you will need to do it yourself (e.g. in your own code, or your asset pipeline).

For more information on premultiplied alpha, and why you might want to use it, see these blog posts.

pub const fn subtract(premultiplied: bool) -> BlendState

The pixel colors of the drawn content will be subtracted from the pixel colors already in the target.

The target’s alpha will not be affected.

If premultiplied is false, the RGB components of the color will be multiplied by the alpha component before blending with the target. If it is true, this step will be skipped, and you will need to do it yourself (e.g. in your own code, or your asset pipeline).

For more information on premultiplied alpha, and why you might want to use it, see these blog posts.

pub const fn multiply() -> BlendState

The pixel colors of the drawn content will be multiplied with the pixel colors already in the target.

The alpha component will also be multiplied.

Trait Implementations

impl Clone for BlendState

fn clone(&self) -> BlendState

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlendState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BlendState

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq<BlendState> for BlendState

fn eq(&self, other: &BlendState) -> bool

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

fn ne(&self, other: &BlendState) -> bool

This method tests for !=.

impl Copy for BlendState

impl Eq for BlendState

impl StructuralEq for BlendState

impl StructuralPartialEq for BlendState