pygfx.materials.Material

class pygfx.materials.Material(*, opacity: float = 1, clipping_planes: Sequence[ABCDTuple] = (), clipping_mode: Literal['ANY', 'ALL'] = 'ANY', alpha_mode: str | None = 'auto', alpha_config: dict | None = None, depth_test: bool = True, depth_compare: str = '<', depth_write: Literal[None, False, True] = None, pick_write: bool = False, alpha_test: float = 0.0, alpha_compare: str = '<', render_queue: int | None = None)

Bases: Trackable

Material base class.

Parameters:

  • opacity (float) – The opacity (a.k.a. alpha value) applied to this material, expressed as a value between 0 and 1. If the material contains any non-opaque fragments, their alphas are simply scaled by this value.

  • clipping_planes (tuple) – A tuple of planes (abcd tuples) in world space. Points in space whose signed distance to the plane is negative are clipped (not rendered). Applies to the object to which this material is attached.

  • clipping_mode (str) – Set the behavior for multiple clipping planes: “any” or “all”. If this is “any” (the default) a fragment is discarded if it is clipped by any clipping plane. If this is “all”, a fragment is discarded only if it is clipped by all of the clipping planes.

  • alpha_mode (str) – How the alpha value of an object is used to to combine the resulting color with the target color texture.

  • alpha_config (dict) – An advanced way to fully control the alpha behaviour. When both alpha_mode and alpha_config are given, the latter is used.

  • depth_test (bool) – Whether the object takes the depth buffer into account (and how). Default True.

  • depth_compare (str) – How to compare depth values (“<”, “<=”, “==”, “!=”, “>=”, “>”). Default “<”.

  • depth_write (bool | None) – Whether the object writes to the depth buffer. With None (default) the value depends on the alpha_config.

  • alpha_test (float) – The alpha test value for this material. Default 0.0, meaning no alpha test is performed.

  • alpha_compare (str) – How to compare alpha values (“<”, “<=”, “==”, “!=”, “>=”, “>”). Default “<”.

property uniform_buffer: Buffer

The uniform buffer object for this material.

Properties that are represented in the buffer can be updated cheaply (i.e. without requiring shader compilation).

property opacity: float

The opacity (a.k.a. alpha value) applied to this material (0..1).

If the material’s color has an alpha smaller than 1, this alpha is multiplied with the opacity.

property clipping_planes: Sequence[ABCDTuple]

A tuple of planes (abcd tuples) in world space. Points in space whose signed distance to the plane is negative are clipped (not rendered). Applies to the object to which this material is attached.

property clipping_plane_count: int

The number of clipping planes (readonly).

property clipping_mode: Literal['ANY', 'ALL']

“ANY” or “ALL”. If this is “ANY” (the default) a fragment is discarded if it is clipped by any clipping plane. If this is “ALL”, a fragment is discarded only if it is clipped by all of the clipping planes.

Type:

Set the behavior for multiple clipping planes

property alpha_mode: AlphaMode

Defines how the the resulting colors are combined with the target color texture.

The material.alpha_mode is the recommended way to specify how an object’s color is combined with the colors of earlier rendered objects. It provides preset configurations covering the majority of use-cases.

The alpha_mode is a convenient way to set alpha_method and alpha_config`. If more control is needed, set ``alpha_config directly.

Modes for method “opaque” (overwrites the value in the output texture):

  • “solid”: alpha is ignored.

  • “solid_premul”: the alpha is multipled with the color (making it darker).

Modes for method “blended” (per-fragment blending, a.k.a. compositing):

  • “auto”: classic alpha blending, with depth_write defaulting to True. See note below.

  • “blend”: classic alpha blending using the over-operator. depth_write defaults to False.

  • “add”: additive blending that adds the fragment color, multiplied by alpha.

  • “subtract”: subtractuve blending that removes the fragment color.

  • “multiply”: multiplicative blending that multiplies the fragment color.

Modes for method “weighted” (order independent blending):

  • “weighted_blend”: weighted blended order independent transparency.

  • “weighted_solid”: fragments are combined based on alpha, but the final alpha is always 1. Great for e.g. image stitching.

Modes for method “stochastic” (alpha represents the chance of a fragment being visible):

  • “dither”: stochastic transparency with blue noise. This mode handles order-independent transparency exceptionally well, but it produces results that can look somewhat noisy.

  • “bayer”: stochastic transparency with an 8x8 Bayer pattern.

Note that the special mode “auto” produces reasonable results for common use-cases and can handle objects that produce a mix of opaque (alpha=1) and transparent (alpha<1) fragments, i.e. it can handle lines, points, and text with material.aa=True. Artifacts can occur when objects are rendered out of order and/or when objects intersect. A different method such as “blend”, “dither”, or “weighted_blend” is then recommended.

Note that for methods ‘opaque’ and ‘stochastic’, the depth_write defaults to True, and for methods ‘blended’ and ‘weighted’ the depth_write defaults to False (except when mode is ‘auto’).

Note that the value of material.alpha_mode can be “custom” in case alpa_config is set to a configuration not covered by a preset mode.

property alpha_method: str

The alpha method being used (readonly).

The alpha method determines the main way how alpha values are used. There are four options:

  • “opaque” means the fragments overwrite value in the color buffer.

  • “blended” means the fragments are blended (composited) with the color buffer.

  • “weighted” means the fragments are blended in a weighted order-independent way.

  • “stochastic” means the fragments are opaque, and alpha represents the chance of a fragment being visible.

The alpha_config dictionary specifies extra parameters that affect the behavour of each alpha method. The alpha_mode is a convenient way to set alpha_config (and alpha_method) using presets

property alpha_config: dict

Dict that defines how the the resulting colors are combined with the target color texture.

The alpha_config property is repesented as a dictionary that fully describes how the object is combined with other objects rendered at the same time. See material.alpha_mode for convenient presets.

All possible alpha configurations are grouped in four methods:

  • “opaque”: colors simply overwrite the texture, no transparency.

  • “blended”: colors are blended with the buffer per-fragment.

  • “weighted”: weighted blended order independent transparency, and variants thereof.

  • “stochastic”: stochastic transparency, alpha represents the chance of a fragment being visible.

The alpha_config dict has at least the following fields:

  • “mode”: the corresponding mode or ‘custom’ (optional when setting).

  • “method”: select the alpha-method (mandatory when setting).

For each method, different options are available, which are represented as items in the alpha_config dict.

Options for method ‘opaque’:

  • “premultiply”: whether to pre-multiply the color with the alpha values.

Options for method ‘blended’:

  • “color_op”: the blend operation/equation, any value from wgpu.BlendOperation. Default “add”.

  • “color_src”: source factor, any value of wgpu.BlendFactor. Mandatory.

  • “color_dst”: destination factor, any value of wgpu.BlendFactor. Mandatory.

  • “color_constant”: represents the constant value of the constant blend color. Default black.

  • “alpha_op”: as color_op but for alpha.

  • “alpha_src”: as color_dst but for alpha.

  • “alpha_dst”: as color_src but for alpha.

  • “alpha_constant”: as color_constant but for alpha (default 0).

Options for method ‘weighted’:

  • “weight”``”: the weight factor as wgsl code. Default “alpha”, which means use the color’s alpha value.

  • “alpha”: the used alpha value. Default “alpha”, which means use as-is. Can e.g. be set to 1.0 so that the alpha channel can be used as the weight factor, while the object is otherwise opaque.

Options for method ‘stochastic’:

  • “pattern”: can be ‘blue-noise’ for blue noise (default), ‘white-noise’ for white noise, and ‘bayer’ for a Bayer pattern.

  • “seed”: can be ‘screen’ to have a uniform pattern for the whole screen, ‘object’ to use a per-object seed, and ‘element’ to have a per-element seed. The default is ‘element’ for the noise patterns and ‘object’ for the bayer pattern.

property render_queue: int

An integer that represents the group that the renderer uses to sort objects.

The property is intended for advanced usage; by default it is determined automatically based on alpha_mode, alpha_method and alpha_test.

The render_queue is a number between 1 and 4999. The builtin values are:

  • 1000: background.

  • 2000: opaque non-blending objects.

  • 2400: opaque objects with a discard based on alpha (i.e. using alpha_test or “stochastic” alpha-method).

  • 2600: objects with alpha-mode ‘auto’.

  • 3000: transparent objects.

  • 4000: overlay.

Objects with render_queue between 1501 and 2500 are sorted front-to-back. Otherwise objects are sorted back-to-front.

It can be tempting to use material.render_queue to control the render order of individual objects, but for that purpose ob.render_order is more appropriate.

property render_queue_is_set

Whether the render_queue property is set. Otherwise it’s auto-determined.

property depth_test: bool

Whether the object takes the depth buffer into account.

When set to True, the fragment’s depth is tested using depth_compare against the depth buffer.

property depth_compare

The way to compare the depth with the value in the buffer.

Possible values are “<”, “<=”, “==”, “!=”, “>=”, “>”. Default “<”. Note that this only applies if depth_test is set to True.

property depth_write: bool

Whether this material writes to the depth buffer, preventing other objects being drawn behind it.

Can be set to:

  • True: yes, write depth.

  • False: no, don’t write depth.

  • None: auto-determine based on alpha_coalpha_mode and alpha_method (default).

The auto-option provides good default behaviour for common use-case, but if you know what you’re doing you should probably just set this value to True or False.

property depth_write_is_set

Whether the depth_write property is set. Otherwise it’s auto-determined.

property alpha_test: float

The alpha test value for this material.

When alpha_test is set to a value > 0, the fragment is discarded if alpha < alpha_test. This is useful for e.g. grass or foliage textures, where the texture has a lot of transparent areas. Also see alpha_compare.

property alpha_compare: str

The way to compare the alpha value.

Possible values are “<”, “<=”, “==”, “!=”, “>=”, “>”. Default “<”. Note that this only applies if the alpha test is performed (i.e. alpha_test is nonzero).

property pick_write: bool

Whether this material is picked by the pointer.