Sampler

class moderngl.Sampler

A Sampler Object is an OpenGL Object that stores the sampling parameters for a Texture access inside of a shader.

When a sampler object is bound to a texture image unit, the internal sampling parameters for a texture bound to the same image unit are all ignored. Instead, the sampling parameters are taken from this sampler object.

Unlike textures, a samplers state can also be changed freely be at any time without the sampler object being bound/in use.

Samplers are bound to a texture unit and not a texture itself. Be careful with leaving samplers bound to texture units as it can cause texture incompleteness issues (the texture bind is ignored).

Sampler bindings do clear automatically between every frame so a texture unit need at least one bind/use per frame.

Create

Context.sampler(repeat_x: bool = True, repeat_y: bool = True, repeat_z: bool = True, filter: Optional[Tuple[int, int]] = None, anisotropy: float = 1.0, compare_func: str = '?', border_color: Optional[Tuple[float, float, float, float]] = None, min_lod: float = - 1000.0, max_lod: float = 1000.0, texture: Optional[moderngl.texture.Texture] = None) moderngl.sampler.Sampler

Create a Sampler object.

Keyword Arguments
  • repeat_x (bool) – Repeat texture on x

  • repeat_y (bool) – Repeat texture on y

  • repeat_z (bool) – Repeat texture on z

  • filter (tuple) – The min and max filter

  • anisotropy (float) – Number of samples for anisotropic filtering. Any value greater than 1.0 counts as a use of anisotropic filtering

  • compare_func – Compare function for depth textures

  • border_color (tuple) – The (r, g, b, a) color for the texture border. When this value is set the repeat_ values are overridden setting the texture wrap to return the border color when outside [0, 1] range.

  • min_lod (float) – Minimum level-of-detail parameter (Default -1000.0). This floating-point value limits the selection of highest resolution mipmap (lowest mipmap level)

  • max_lod (float) – Minimum level-of-detail parameter (Default 1000.0). This floating-point value limits the selection of the lowest resolution mipmap (highest mipmap level)

  • texture (Texture) – The texture for this sampler

Methods

Sampler.use(location: int = 0) None

Bind the sampler to a texture unit.

Parameters

location (int) – The texture unit

Sampler.clear(location: int = 0) None

Clear the sampler binding on a texture unit.

Parameters

location (int) – The texture unit

Sampler.assign(index: int) Tuple[moderngl.sampler.Sampler, int]

Helper method for assigning samplers to scopes.

Example:

s1 = ctx.sampler(...)
s2 = ctx.sampler(...)
ctx.scope(samplers=(s1.assign(0), s1.assign(1)), ...)
Returns

(self, index) tuple

Sampler.release() None

Release/destroy the ModernGL object.

Attributes

Sampler.texture
Sampler.repeat_x

The x repeat flag for the sampler (Default True).

Example:

# Enable texture repeat (GL_REPEAT)
sampler.repeat_x = True

# Disable texture repeat (GL_CLAMP_TO_EDGE)
sampler.repeat_x = False
Type

bool

Sampler.repeat_y

The y repeat flag for the sampler (Default True).

Example:

# Enable texture repeat (GL_REPEAT)
sampler.repeat_y = True

# Disable texture repeat (GL_CLAMP_TO_EDGE)
sampler.repeat_y = False
Type

bool

Sampler.repeat_z

The z repeat flag for the sampler (Default True).

Example:

# Enable texture repeat (GL_REPEAT)
sampler.repeat_z = True

# Disable texture repeat (GL_CLAMP_TO_EDGE)
sampler.repeat_z = False
Type

bool

Sampler.filter

The minification and magnification filter for the sampler.

(Default (moderngl.LINEAR. moderngl.LINEAR))

Example:

sampler.filter == (moderngl.NEAREST, moderngl.NEAREST)
sampler.filter == (moderngl.LINEAR_MIPMAP_LINEAR, moderngl.LINEAR)
sampler.filter == (moderngl.NEAREST_MIPMAP_LINEAR, moderngl.NEAREST)
sampler.filter == (moderngl.LINEAR_MIPMAP_NEAREST, moderngl.NEAREST)
Type

tuple

Sampler.compare_func

The compare function for a depth textures (Default '?').

By default samplers don’t have depth comparison mode enabled. This means that depth texture values can be read as a sampler2D using texture() in a GLSL shader by default.

When setting this property to a valid compare mode, GL_TEXTURE_COMPARE_MODE is set to GL_COMPARE_REF_TO_TEXTURE so that texture lookup functions in GLSL will return a depth comparison result instead of the actual depth value.

Accepted compare functions:

.compare_func = ''    # Disale depth comparison completely
sampler.compare_func = '<='  # GL_LEQUAL
sampler.compare_func = '<'   # GL_LESS
sampler.compare_func = '>='  # GL_GEQUAL
sampler.compare_func = '>'   # GL_GREATER
sampler.compare_func = '=='  # GL_EQUAL
sampler.compare_func = '!='  # GL_NOTEQUAL
sampler.compare_func = '0'   # GL_NEVER
sampler.compare_func = '1'   # GL_ALWAYS
Type

tuple

Sampler.anisotropy

Number of samples for anisotropic filtering (Default 1.0).

The value will be clamped in range 1.0 and ctx.max_anisotropy.

Any value greater than 1.0 counts as a use of anisotropic filtering:

# Disable anisotropic filtering
sampler.anisotropy = 1.0

# Enable anisotropic filtering suggesting 16 samples as a maximum
sampler.anisotropy = 16.0
Type

float

Sampler.border_color

The (r, g, b, a) color for the texture border (Default (0.0, 0.0, 0.0, 0.0)).

When setting this value the repeat_ values are overridden setting the texture wrap to return the border color when outside [0, 1] range.

Example:

# Red border color
sampler.border_color = (1.0, 0.0, 0.0, 0.0)
Type

tuple

Sampler.min_lod

Minimum level-of-detail parameter (Default -1000.0).

This floating-point value limits the selection of highest resolution mipmap (lowest mipmap level)

Type

float

Sampler.max_lod

Minimum level-of-detail parameter (Default 1000.0).

This floating-point value limits the selection of the lowest resolution mipmap (highest mipmap level)

Type

float

Sampler.extra

Any - Attribute for storing user defined objects

Sampler.mglo

Internal representation for debug purposes only.

Sampler.ctx

The context this object belongs to