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 and BufferDescription 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 ctx: Context

The context this geometry belongs to.

property index_buffer: Buffer | None

Index/element buffer if supplied at creation.

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

flush() None[source]

Flush all the internally generated VertexArrays.

The Geometry instance will store a VertexArray for every unique set of input attributes it stumbles over when rendering and transform calls are issued. This data is usually pretty light weight and usually don’t need flushing.

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

  • instancedTrue if this is per instance data

buffer: Buffer

The Buffer this description object describes

attributes

List of string attributes

normalized: set[str]

List of normalized attributes

instanced: bool

Instanced flag (bool)

formats: list[AttribFormat]

Formats of each attribute

stride: int

The byte stride of the buffer

num_vertices: int

Number of vertices in the buffer

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

property ctx: Context

The Context this object belongs to.

property program: Program

The assigned program.

property ibo: Buffer | None

Element/index buffer.

property num_vertices: int

The number of vertices.

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