OpenGL Context
Contents
arcade.ArcadeContext
- class arcade.ArcadeContext(window: pyglet.window.BaseWindow, gc_mode: str = 'auto')[source]
Bases:
arcade.gl.context.Context
An OpenGL context implementation for Arcade with added custom features. This context is normally accessed thought
arcade.Window.ctx
.Pyglet users can use the base Context class and extend that as they please.
This is part of the low level rendering API in arcade and is mainly for more advanced usage
- Parameters
window (pyglet.window.Window) – The pyglet window
gc_mode (str) – The garbage collection mode for opengl objects.
auto
(default) is just what we would expect in python whilecontext_gc
requires you to callContext.gc()
. The latter can be useful when using multiple threads when it’s not clear what thread will gc the object.
- classmethod activate(ctx: arcade.gl.context.Context)
Mark a context as the currently active one
- property blend_func: Tuple[int, int]
Get or the blend function:
ctx.blend_func = ctx.ONE, ctx.ONE
- Type
tuple (src, dst)
- buffer(*, data: Optional[Any] = None, reserve: int = 0, usage: str = 'static') arcade.gl.buffer.Buffer
Create a new OpenGL Buffer object.
- copy_framebuffer(src: arcade.gl.framebuffer.Framebuffer, dst: arcade.gl.framebuffer.Framebuffer)
Copies/blits a framebuffer to another one.
This operation many restrictions to ensure it works across different platforms and drivers:
The source and destination framebuffer must be the same size
The formats of the attachments must be the same
Only the source framebuffer can be multisampled
Framebuffers cannot have interger attachments
- Parameters
src (Framebuffer) – The framebuffer to copy from
dst (Framebuffer) – The framebuffer we copy to
- property default_atlas: arcade.texture_atlas.TextureAtlas
The default texture atlas. This is created when arcade is initialized. All sprite lists will use use this atlas unless a different atlas is passned in the
SpriteList
constructor.- Type
- depth_texture(size: Tuple[int, int], *, data=None) arcade.gl.texture.Texture
Create a 2D depth texture
- disable(*args)
Disable one or more context flags:
# Single flag ctx.disable(ctx.BLEND) # Multiple flags ctx.disable(ctx.DEPTH_TEST, ctx.CULL_FACE)
- enable(*flags)
Enables one or more context flags:
# Single flag ctx.enable(ctx.BLEND) # Multiple flags ctx.enable(ctx.DEPTH_TEST, ctx.CULL_FACE)
- enable_only(*args)
Enable only some flags. This will disable all other flags. This is a simple way to ensure that context flag states are not lingering from other sections of your code base:
# Ensure all flags are disabled (enable no flags) ctx.enable_only() # Make sure only blending is enabled ctx.enable_only(ctx.BLEND) # Make sure only depth test and culling is enabled ctx.enable_only(ctx.DEPTH_TEST, ctx.CULL_FACE)
- enabled(*flags)
Temporarily change enabled flags:
with ctx.enabled(ctx.BLEND, ctx.CULL_FACE): # Render something
- enabled_only(*flags)
Temporarily change enabled flags:
with ctx.enabled_only(ctx.BLEND, ctx.CULL_FACE): # Render something
- property error: Optional[str]
Check OpenGL error
Returns a string representation of the occurring error or
None
of no errors has occurred.Example:
err = ctx.error if err: raise RuntimeError("OpenGL error: {err}")
- Type
- property fbo: arcade.gl.framebuffer.Framebuffer
Get the currently active framebuffer. This property is read-only
- finish() None
Wait until all OpenGL rendering commands are completed.
This function will actually stall until all work is done and may have severe performance implications.
- flush()
A suggestion to the driver to execute all the queued drawing calls even if the queue is not full yet. This is not a blocking call and only a suggestion. This can potentially be used for speedups when we don’t have anything else to render.
- framebuffer(*, color_attachments: Optional[Union[arcade.gl.texture.Texture, List[arcade.gl.texture.Texture]]] = None, depth_attachment: Optional[arcade.gl.texture.Texture] = None) arcade.gl.framebuffer.Framebuffer
Create a Framebuffer.
- Parameters
color_attachments (List[arcade.gl.Texture]) – List of textures we want to render into
depth_attachment (arcade.gl.Texture) – Depth texture
- Return type
- gc() int
Run garbage collection of OpenGL objects for this context. This is only needed when
gc_mode
iscontext_gc
.- Returns
The number of resources destroyed
- Return type
- property gc_mode: str
Set the garbage collection mode for OpenGL resources. Supported modes are:
# default: Auto ctx.gc_mode = “auto”
# Defer garbage collection until ctx.gc() is called # This can be useful to enforce the main thread to # run garbage collection of opengl resources ctx.gc_mode = “context_gc”
- geometry(content: Optional[Sequence[arcade.gl.types.BufferDescription]] = None, index_buffer: Optional[arcade.gl.buffer.Buffer] = None, mode: Optional[int] = None, index_element_size: int = 4)
Create a Geomtry instance.
- Parameters
content (list) – List of
BufferDescription
(optional)index_buffer (Buffer) – Index/element buffer (optional)
mode (int) – The default draw mode (optional)
mode – The default draw mode (optional)
index_element_size (int) – Byte size of the index buffer type. Can be 1, 2 or 4 (8, 16 or 32 bit unsigned integer)
- property gl_version: Tuple[int, int]
The OpenGL version as a 2 component tuple
- Type
tuple (major, minor) version
- load_compute_shader(path: Union[str, pathlib.Path]) arcade.gl.compute_shader.ComputeShader [source]
Loads a compute shader.
- Parameters
path (Union[str,pathlib.Path]) – Path to texture
- load_program(*, vertex_shader: Union[str, pathlib.Path], fragment_shader: Optional[Union[str, pathlib.Path]] = None, geometry_shader: Optional[Union[str, pathlib.Path]] = None, tess_control_shader: Optional[Union[str, pathlib.Path]] = None, tess_evaluation_shader: Optional[Union[str, pathlib.Path]] = None, defines: Optional[dict] = None) arcade.gl.program.Program [source]
Create a new program given a file names that contain the vertex shader and fragment shader. Note that fragment and geometry shader are optional for when transform shaders are loaded.
This method also supports the
:resources:
prefix. It’s recommended to use absolute paths, but not required.Example:
# The most common use case if having a vertex and fragment shader program = window.ctx.load_program( vertex_shader="vert.glsl", fragment_shader="frag.glsl", )
- Parameters
vertex_shader (Union[str,pathlib.Path]) – path to vertex shader
fragment_shader (Union[str,pathlib.Path]) – path to fragment shader (optional)
geometry_shader (Union[str,pathlib.Path]) – path to geometry shader (optional)
defines (dict) – Substitute
#define
values in the sourcetess_control_shader (Union[str,pathlib.Path]) – Tessellation Control Shader
tess_evaluation_shader (Union[str,pathlib.Path]) – Tessellation Evaluation Shader
- load_texture(path: Union[str, pathlib.Path], *, flip: bool = True, build_mipmaps: bool = False) arcade.gl.texture.Texture [source]
Loads and creates an OpenGL 2D texture. Currently all textures are converted to RGBA.
Example:
texture = window.ctx.load_texture("background.png")
- Parameters
path (Union[str,pathlib.Path]) – Path to texture
flip (bool) – Flips the image upside down
build_mipmaps (bool) – Build mipmaps for the texture
- objects: Deque[Any]
Collected objects to gc when gc_mode is “context_gc”
- property patch_vertices: int
Get or set number of vertices that will be used to make up a single patch primitive. Patch primitives are consumed by the tessellation control shader (if present) and subsequently used for tessellation.
- Type
- program(*, vertex_shader: str, fragment_shader: Optional[str] = None, geometry_shader: Optional[str] = None, tess_control_shader: Optional[str] = None, tess_evaluation_shader: Optional[str] = None, defines: Optional[Dict[str, str]] = None) arcade.gl.program.Program
Create a
Program
given the vertex, fragment and geometry shader.- Parameters
vertex_shader (str) – vertex shader source
fragment_shader (str) – fragment shader source (optional)
geometry_shader (str) – geometry shader source (optional)
tess_control_shader (str) – tessellation control shader source (optional)
tess_evaluation_shader (str) – tessellation evaluation shader source (optional)
defines (dict) – Substitute #defines values in the source (optional)
- Return type
- property projection_2d: Tuple[float, float, float, float]
Get or set the global orthogonal projection for arcade.
This projection is used by sprites and shapes and is represented by four floats:
(left, right, bottom, top)
- property projection_2d_matrix: pyglet.math.Mat4
Get the current projection matrix. This 4x4 float32 matrix is calculated when setting
projection_2d
.- Type
Mat4
- pyglet_rendering()[source]
Context manager for pyglet rendering. Since arcade and pyglet needs slightly different states we needs some initialization and cleanup.
Examples:
with window.ctx.pyglet_rendering(): # Draw with pyglet here
- property screen: arcade.gl.framebuffer.Framebuffer
The framebuffer for the window.
- Type
Framebuffer
- texture(size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Optional[Any] = None, wrap_x: Optional[ctypes.c_uint] = None, wrap_y: Optional[ctypes.c_uint] = None, filter: Optional[Tuple[ctypes.c_uint, ctypes.c_uint]] = None, samples: int = 0) arcade.gl.texture.Texture
Create a 2D Texture.
Wrap modes:
GL_REPEAT
,GL_MIRRORED_REPEAT
,GL_CLAMP_TO_EDGE
,GL_CLAMP_TO_BORDER
Minifying filters:
GL_NEAREST
,GL_LINEAR
,GL_NEAREST_MIPMAP_NEAREST
,GL_LINEAR_MIPMAP_NEAREST
GL_NEAREST_MIPMAP_LINEAR
,GL_LINEAR_MIPMAP_LINEAR
Magnifying filters:
GL_NEAREST
,GL_LINEAR
- Parameters
components (int) – Number of components (1: R, 2: RG, 3: RGB, 4: RGBA)
dtype (str) – The data type of each component: f1, f2, f4 / i1, i2, i4 / u1, u2, u4
data (Any) – The texture data (optional). Can be bytes or an object supporting the buffer protocol.
wrap_x (GLenum) – How the texture wraps in x direction
wrap_y (GLenum) – How the texture wraps in y direction
filter (Tuple[GLenum,GLenum]) – Minification and magnification filter
samples (int) – Creates a multisampled texture for values > 0
- property viewport: Tuple[int, int, int, int]
Get or set the viewport for the currently active framebuffer. The viewport simply describes what pixels of the screen OpenGL should render to. Normally it would be the size of the window’s framebuffer:
# 4:3 screen ctx.viewport = 0, 0, 800, 600 # 1080p ctx.viewport = 0, 0, 1920, 1080 # Using the current framebuffer size ctx.viewport = 0, 0, *ctx.screen.size
- Type
tuple (x, y, width, height)
- property window: pyglet.window.BaseWindow
The window this context belongs to.
- Type
pyglet.Window