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
usingtexture()
in a GLSL shader by default.When setting this property to a valid compare mode,
GL_TEXTURE_COMPARE_MODE
is set toGL_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
andctx.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