Geometry
- class arcade.gl.Geometry(ctx: Context, content: Sequence[BufferDescription] | None, index_buffer: Buffer | None = None, mode: int | None = None, index_element_size: int = 4)[source]
Bases:
A higher level abstraction of the VertexArray.
It generates VertexArray instances on the fly internally matching the incoming program. This means we can render the same geometry with different programs as long as the
Program
andBufferDescription
have compatible attributes. This is an extremely powerful concept that allows for very flexible rendering pipelines and saves the user from a lot of manual bookkeeping.Geometry objects should be created through
arcade.gl.Context.geometry()
- Parameters:
ctx – The context this object belongs to
content – List of BufferDescriptions
index_buffer – Index/element buffer
mode – The default draw mode
index_element_size – Byte size of the index buffer datatype. Can be 1, 2 or 4 (8, 16 or 32bit integer)
- property num_vertices: int
Get or set the number of vertices.
Be careful when modifying this properly and be absolutely sure what you are doing.
- append_buffer_description(descr: BufferDescription)[source]
Append a new BufferDescription to the existing Geometry.
Warning
Geometry cannot contain two BufferDescriptions which share an attribute name.
- instance(program: Program) VertexArray [source]
Get the
arcade.gl.VertexArray
compatible with this program.
- render(program: Program, *, mode: c_uint | int | None = None, first: int = 0, vertices: int | None = None, instances: int = 1) None [source]
Render the geometry with a specific program.
The geometry object will know how many vertices your buffers contains so overriding vertices is not needed unless you have a special case or have resized the buffers after the geometry instance was created.
- Parameters:
program – The Program to render with
mode – Override what primitive mode should be used
first – Offset start vertex
vertices – Override the number of vertices to render
instances – Number of instances to render
- render_indirect(program: Program, buffer: Buffer, *, mode: c_uint | int | None = None, count: int = -1, first: int = 0, stride: int = 0) None [source]
Render the VertexArray to the framebuffer using indirect rendering.
Warning
This requires OpenGL 4.3
The following structs are expected for the buffer:
// Array rendering - no index buffer (16 bytes) typedef struct { uint count; uint instanceCount; uint first; uint baseInstance; } DrawArraysIndirectCommand; // Index rendering - with index buffer 20 bytes typedef struct { GLuint count; GLuint instanceCount; GLuint firstIndex; GLuint baseVertex; GLuint baseInstance; } DrawElementsIndirectCommand;
The
stride
is the byte stride between every rendering command in the buffer. By default we assume this is 16 for array rendering (no index buffer) and 20 for indexed rendering (with index buffer)- Parameters:
program – The program to execute
buffer – The buffer containing one or multiple draw parameters
mode – Primitive type to render. TRIANGLES, LINES etc.
count – The number if indirect draw calls to run. If omitted all draw commands in the buffer will be executed.
first – The first indirect draw call to start on
stride – The byte stride of the draw command buffer. Keep the default (0) if the buffer is tightly packed.
- transform(program: Program, buffer: Buffer | list[Buffer], *, first: int = 0, vertices: int | None = None, instances: int = 1, buffer_offset: int = 0) None [source]
Render with transform feedback. Instead of rendering to the screen or a framebuffer the result will instead end up in the
buffer
we supply.If a geometry shader is used the output primitive mode is automatically detected.
- Parameters:
program – The Program to render with
buffer – The buffer(s) we transform into. This depends on the programs
varyings_capture_mode
. We can transform into one buffer interleaved or transform each attribute into separate buffers.first – Offset start vertex
vertices – Number of vertices to render
instances – Number of instances to render
buffer_offset – Byte offset for the buffer
- class arcade.gl.BufferDescription(buffer: Buffer, formats: str, attributes: Sequence[str], normalized: Iterable[str] | None = None, instanced: bool = False)[source]
Bases:
Buffer Object description used with
arcade.gl.Geometry
.This class provides a Buffer object with a description of its content, allowing the a
Geometry
object to correctly map shader attributes to a program/shader.The formats is a string providing the number and type of each attribute. Currently we only support f (float), i (integer) and B (unsigned byte).
normalized
enumerates the attributes which must have their values normalized. This is useful for instance for colors attributes given as unsigned byte and normalized to floats with values between 0.0 and 1.0.instanced
allows this buffer to be used as instanced buffer. Each value will be used once for the whole geometry. The geometry will be repeated a number of times equal to the number of items in the Buffer.Example:
# Describe my_buffer # It contains two floating point numbers being a 2d position # and two floating point numbers being texture coordinates. # We expect the shader using this buffer to have an in_pos and in_uv attribute (exact name) BufferDescription( my_buffer, '2f 2f', ['in_pos', 'in_uv'], )
- Parameters:
buffer – The buffer to describe
formats – The format of each attribute
attributes – List of attributes names (strings)
normalized – list of attribute names that should be normalized
instanced –
True
if this is per instance data
- attributes
List of string attributes
- class arcade.gl.VertexArray(ctx: Context, program: Program, content: Sequence[BufferDescription], index_buffer: Buffer | None = None, index_element_size: int = 4)[source]
Bases:
Wrapper for Vertex Array Objects (VAOs).
This objects should not be instantiated from user code. Use
arcade.gl.Geometry
instead. It will create VAO instances for you automatically. There is a lot of complex interaction between programs and vertex arrays that will be done for you automatically.- Parameters:
ctx – The context this object belongs to
program – The program to use
content (optional) – List of BufferDescriptions
index_buffer (optional) – Index/element buffer
index_element_size (optional) – Byte size of the index buffer datatype.
- glo
The OpenGL resource ID
- delete() None [source]
Destroy the underlying OpenGL resource.
Don’t use this unless you know exactly what you are doing.
- static delete_glo(ctx: Context, glo: gl.GLuint) None [source]
Delete the OpenGL resource.
This is automatically called when this object is garbage collected.
- render(mode: c_uint | int, first: int = 0, vertices: int = 0, instances: int = 1) None [source]
Render the VertexArray to the currently active framebuffer.
- Parameters:
mode – Primitive type to render. TRIANGLES, LINES etc.
first – The first vertex to render from
vertices – Number of vertices to render
instances – OpenGL instance, used in using vertices over and over
- render_indirect(buffer: Buffer, mode: c_uint | int, count, first, stride) None [source]
Render the VertexArray to the framebuffer using indirect rendering.
Warning
This requires OpenGL 4.3
- Parameters:
buffer – The buffer containing one or multiple draw parameters
mode – Primitive type to render. TRIANGLES, LINES etc.
count – The number if indirect draw calls to run
first – The first indirect draw call to start on
stride – The byte stride of the draw command buffer. Keep the default (0) if the buffer is tightly packed.
- transform_interleaved(buffer: Buffer, mode: c_uint | int, output_mode: c_uint | int, first: int = 0, vertices: int = 0, instances: int = 1, buffer_offset=0) None [source]
Run a transform feedback.
- Parameters:
buffer – The buffer to write the output
mode – The input primitive mode
output_mode – The output primitive mode
first – Offset start vertex
vertices – Number of vertices to render
instances – Number of instances to render
buffer_offset – Byte offset for the buffer (target)
- transform_separate(buffers: list[Buffer], mode: c_uint | int, output_mode: c_uint | int, first: int = 0, vertices: int = 0, instances: int = 1, buffer_offset=0) None [source]
Run a transform feedback writing to separate buffers.
- Parameters:
buffers – The buffers to write the output
mode – The input primitive mode
output_mode – The output primitive mode
first – Offset start vertex
vertices – Number of vertices to render
instances – Number of instances to render
buffer_offset – Byte offset for the buffer (target)
- arcade.gl.geometry.quad_2d_fs() Geometry [source]
Creates a screen aligned quad using normalized device coordinates
- arcade.gl.geometry.quad_2d(size: tuple[float, float] = (1.0, 1.0), pos: tuple[float, float] = (0.0, 0.0)) Geometry [source]
Creates 2D quad Geometry using 2 triangle strip with texture coordinates.
By default a unit quad is created with the center at (0, 0).
- Parameters:
size – width and height of the quad
pos – Center position x and y
- arcade.gl.geometry.screen_rectangle(bottom_left_x: float, bottom_left_y: float, width: float, height: float) Geometry [source]
Creates screen rectangle using 2 triangle strip with texture coordinates.
This can create a rectangle in normalized device coordinates or projection space.
- Parameters:
bottom_left_x – Bottom left x position
bottom_left_y – Bottom left y position
width – Width of the rectangle
height – Height of the rectangle
- arcade.gl.geometry.cube(size: tuple[float, float, float] = (1.0, 1.0, 1.0), center: tuple[float, float, float] = (0.0, 0.0, 0.0)) Geometry [source]
Creates a cube with normals and texture coordinates.
By default a unit cube is created with the center at (0, 0, 0).
- Parameters:
size – Size of the cube as a 3-component tuple
center – Center of the cube as a 3-component tuple
- Returns:
A Geometry instance containing a cube