pyvista.Actor.add_shader_replacement

Actor.add_shader_replacement(

shader_type: ShaderType | str,

original: str,

replacement: str,

*,

replace_first: bool = True,

replace_all: bool = False,

_feature_name: str = '_user',

) → None

Add a GLSL shader replacement to this actor.

Added in version 0.48.

This wraps VTK’s shader replacement API, providing conflict detection and tracking so that multiple independent shader features can coexist safely on the same actor.

Parameters:

shader_typeShaderType | str

Type of shader to modify. Accepts a ShaderType enum value or a string. One of 'vertex', 'fragment', or 'geometry'.

originalstr

The VTK shader tag to replace (e.g., '//VTK::Color::Impl').

replacementstr

The GLSL replacement code.

replace_firstbool, default: True

Whether the replacement is applied before VTK’s standard shader substitutions.

replace_allbool, default: False

Whether to replace all occurrences of original.

_feature_namestr, default: ‘_user’

Internal key used to track which feature owns this replacement. End users should not need to change this. Built-in features use dedicated keys like 'mip' and 'point_sprite'.

Raises:

ValueError

If shader_type is invalid or if another feature already targets the same shader tag.

Examples

Add a custom fragment shader that discards pixels outside a circle.

>>> import pyvista as pv
>>> mesh = pv.Sphere()
>>> pl = pv.Plotter()
>>> actor = pl.add_mesh(mesh, style='points', point_size=20)
>>> actor.add_shader_replacement(
...     'fragment',
...     '//VTK::Color::Impl',
...     '//VTK::Color::Impl\n'
...     'vec2 p = gl_PointCoord * 2.0 - 1.0;\n'
...     'if (dot(p, p) > 1.0) discard;\n',
... )