Rendering¶

Most of these Classes have cdefed functions that cannot be read by Sphinx. Read the source if you want to find out more about using them.

VBOs¶

class kivent_core.rendering.fixedvbo.FixedVBO¶

This is a VBO that has a fixed size for the amount of vertex data. While the MemoryBlock will hold a fixed amount of data, it is possible we will upload a different amount of data per-frame to GL. This allows us to render up to the maximum amount that will fill MemoryBlock without having to reallocate memory on the cpu side of things.

Attributes: (Cython Access Only)

memory_block (MemoryBlock): MemoryBlock holding the data for this VBO.

usage (int): The usage hint for this VBO, currently only GL_STREAM_DRAW is supported. Pass in ‘stream’ when initializing. Any other argument will raise VBOUsageException.

target (int): The target of the buffer when binding. Can be either GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER at the moment. When initializing pass in either ‘array’ or ‘elements’ respectively. Any other argument with raise a VBOTargetException

flags (short): State used by Kivy during rendering.

id (GLuint): The id assigned by GL for this buffer. Returned from glGenBuffers.

size_last_frame (unsigned int): The number of elements rendered during the last frame. Used to determine whether we should glBufferData or glBufferSubData when updating the vbo.

data_size (unsigned int): The amount of data to be rendered next frame.

vertex_format (KEVertexFormat): The object containing data about the vertex format for this VBO.

Instructions¶

class kivent_core.rendering.cmesh.CMesh(**kwargs)¶

Models¶

class kivent_core.rendering.model.VertexModel¶

A VertexModel allows you to interact with arbitrary structs with GL types. A Model is made up of 2 main parts, the vertex data associated with each vertex in the model, and the indices describing how those vertices are related. For instance a sprite would be represented as a 4 vertex quad, with indices: [0, 1, 2, 2, 3, 0]

The quad is constructed out of 2 triangle faces, the triangle reprsented by vertices 0, 1, 2, and the triangle represented by 2, 3, 0, this looks like:

1__2 | /| 0/_3

A Vertex can hold arbitrary data, but it will typically hold its x, y position on the screen at the very least, and very often the u,v position mapping texture coordinates to the geometric.

A vertex of the model can be accessed by indexing into the object

vertex_model = VertexModel(4, 6, format_config, index_buffer,
    vertex_buffer, 'my_model_name')
vertex = vertex_model[0]

This will retrieve a Vertex object that can manipulate the data of the specified vertex. You should be careful about holding onto the vertex objects as if you either adjust the index_count or vertex_count the location in memory WILL change, and the old objects will not manipulate the correct data. In addition it is possible for a VertexModel to be GC’d while you keep a Vertex alive, also resulting into the Vertex manipulating the wrong data.

You can change the size of either the index or vertex data on a model, but you cannot change its FormatConfig. If you need to change a model’s vertex format, you should instead create a new model. If you change a model, you should first unbatch all entities that are using that model and then rebatch them after changes have been completed. If your model is only used by a single entity, the RenderComponent properties will assist in doing this.

[Add Note about model entity tracking when implemented]

Attributes:

Attributes: (Cython Access Only)

vertices_block (MemoryBlock): The MemoryBlock holding the vertex data for this model.

indices_block (MemoryBlock): The MemoryBlock holding the indices data for this model.

index_buffer (Buffer): The Buffer from which we will actually allocate the indices_block. Used when index_count changes.

vertex_buffer (Buffer): The Buffer from which we will actually allocate the vertices_block. Used when vertex_count changes.

Attributes:

index_count (unsigned int): The number of indices in your model. Unbatch any active entities before setting and rebatch afterwards.

vertex_count (unsigned int): The number of vertices in your model. Unbatch any active entities before setting and rebatch afterwards.

name (str): The name of this model, as kept track of by the ModelManager.

format_config (FormatConfig): The vertex format for this model. Will be set on creation and should not be changed.

vertices (list): Returns a list of Vertex objects for every vertex in the model. Be careful about keeping the results around. You need to retrieve a new copy of the list if you for instance change vertex_count. You can supply a dict of key: index of vertex, value dict of attribute, value pairs in order to set all vertices at once.

For instance:

model.vertices = {
    1: {'pos': (-5., -5.), uvs: (0., 0.)},
    2: {'pos': (-5., 5.), uvs: (0., 1.)},
    3: {'pos': (5., 5.), uvs: (1., 1.)},
    4: {'pos': (5., -5.), uvs: (1., 0.)},
}

indices (list): Returns a list of unsigned shorts specifying the indices for this model. This is a copy of the actual data, do not manipulate the returned list directly instead:

vertex_model.indices = [new index data]

add_all_vertex_attribute(self, str attribute_name, value)¶

Adds value to the specified attribute of all vertices. More optimized than doing the same thing on the list provided by vertices as only one Vertex will be made and its pointer shifted.

Args:

attribute_name (str): The name of the attribute we will be modifying.

value (any): The value or values to set the attributes of each vertex to. If the attribute is an array, you can either provide a separate value for each place or one value that will be added to all places.

center_model(self)¶: Centers the models vertices around (0, 0). Only works if the vertex format has a pos method.

copy_vertex_model(self, VertexModel to_copy)¶

Copies all the data from the provided VertexModel to this one. Will possibly change vertex_count and index_count so make sure to unbatch and rebatch any Entity referencing this model before and after calling copy_vertex_model. If you know the models have the same counts you do not need to do so.

Args:: to_copy (VertexModel): The model to copy.

free_memory(self)¶: Frees the allocated memory. Do not use the VertexModel after free_memory has been called. Typically called internally by the ModelManager.

mult_all_vertex_attribute(self, str attribute_name, value)¶

Mulitplies value to the specified attribute of all vertices. More optimized than doing the same thing on the list provided by vertices as only one Vertex will be made and its pointer shifted.

Args:

attribute_name (str): The name of the attribute we will be modifying.

value (any): The value or values to set the attributes of each vertex to. If the attribute is an array, you can either provide a separate value for each place or one value that will be mulitplied to all places.

set_all_vertex_attribute(self, str attribute_name, value)¶

Sets all vertices attribute to the provided value. More optimized than doing the same thing on the list provided by vertices as only one Vertex will be made and its pointer shifted.

Args:

attribute_name (str): The name of the attribute we will be modifying.

value (any): The value or values to set the attributes of each vertex to.

set_textured_rectangle(self, float width, float height, list uvs)¶

Prepare a 4 vertex_count, 6 index_count textured quad (sprite) of size: width x height. Normally called internally when creating sprites. Will assume your vertex format have a ‘pos’ and ‘uvs’ array of size 2.

Args:

width (float): Width of the quad.

height (float): Height of the quad

uvs (list): Should be a list of 4 values representing the uv texture coordinates of the quad. For a texture that took up the whole size of the image this will be [0., 0., 1., 1.]. uv coordinates are normalized inside their texture.

class kivent_core.rendering.model.Vertex¶

The Vertex class allows you to interface with the underlying C structs representing a VertexModel’s vertices from Python. It does this by automatically wrapping the struct based on data from kivent_core.rendering.vertex_formats.

You will not create a Vertex manually, instead it will typically be returned from indexing into a VertexModel. For instance:

vertex = instance_of_VertexModel[0] #retrieve the first vertex
pos = vertex.pos #retrieve data from a vertex
vertex.pos = [1., 2.] #set data

The attributes for a Vertex will depend on the actual vertex format of the model. See the documentation for kivent_core.rendering.vertex_formats.VertexFormatRegister for more information.

Keep in mind: When getting data from a Vertex you are retrieving a copy of that data. Not the original, modifying the returned list will not affect the underlying data, instead you must call set.

Vertex Formats¶

class kivent_core.rendering.vertex_format.KEVertexFormat(size_in_bytes, *fmt)¶

VertexFormat is used to describe the layout of the vertex data stored in vertex arrays/vbo’s. It differs from the Kivy VertexFormat by tracking the offsets of the individual attributes so that you can interleave non-homogenous data types.

Supported attribute types are:: ‘float’: GLfloat ‘byte’: GLbyte ‘ubyte’: GLubyte ‘int’: GLint ‘uint’: GLuint ‘short’: GLshort ‘ushort’: GLushort
Attributes: (Cython Access Only): attr_offsets (Py_ssize_t*): Pointer to the array containing the offsets for each attribute of the VertexFormat. Separate from the rest of the data to maintain compatibility with the Kivy VertexFormat.

Frame Objects¶

class kivent_core.rendering.frame_objects.FixedFrameData¶

The FixedFrameData manages 2 FixedVBO, suitable for rendering using the GL_TRIANGLES mode. One FixedVBO will hold the indices data and the other the actual vertex data.

Attributes: (Cython Access Only)

index_vbo (FixedVBO): The FixedVBO holding indices data. Will have the target: GL_ELEMENTS_ARRAY_BUFFER.

vertex_vbo (FixedVBO): The FixedVBO holding vertex data. Will have the target: GL_ARRAY_BUFFER.

Batching¶

class kivent_core.rendering.batching.IndexedBatch¶

The IndexedBatch represents a collection of FixedFrameData vbos, suitable for rendering using GL_TRIANGLES mode. Data will be split into both an indices VBO and a vertices VBO, and explicit multibuffering will be performed. Drawing will be performed by calling glDrawElements. Each frame the FixedFrameData at position current_frame % frame_count in the frame_data list will be used for rendering.

Attributes: (Cython Access Only)

frame_data (list): List of FixedFrameData objects for this batch.

current_frame (unsigned int): Every frame rendered (calling draw_frame) will increment this by 1.

frame_count (unsigned int): Number of FixedFrameData objects in the frame_data list. The number of buffers to use.

tex_key (unsigned int): Identifier for the texture resource that will be used when drawing the entities in this batch. All entities must share the same texture.

batch_id (unsigned int): The identifier for this batch, will be set by the BatchManager controlling this batch. Defaults to <unsigned int>-1.

mode (GLuint): The drawing mode for this batch. Will be one of GL_TRIANGLES, GL_LINES, GL_POINTS, GL_TRIANGLE_FAN, GL_LINE_STRIP, GL_LINE_LOOP, GL_TRIANGLE_STRIP.

mesh_instruction (object): Reference to the actual instruction that will be added to the canvas of the parent renderer.

entity_components (ComponentPointerAggregator): Helper object for retrieving pointers to the components of entities added to this batch.

class kivent_core.rendering.batching.BatchManager¶

The BatchManager is responsible for managing a fixed amount of IndexedBatch to render more entities than will fit in a single IndexedBatch. It handles appropriate creation and reusing of these batches for you, and typically you will only care about batch_entity and unbatch_entity functions. All entities drawn by BatchManager must share the same KEVertexFormat, however they can have different textures.

Keep in mind that each texture used will require a different batch so you should be careful not to use too many textures as the maximum amount of textures that can be used is the max_batches, and then we will be unable to render more than one batch worth of vertices per texture. This means you should try to combine textures into a single atlas as often as possible.

Note at the moment only GL_TRIANGLES drawing mode is supported.

Attributes: (Cython Access Only)

batch_block (MemoryBlock): The MemoryBlock reserved for holding vertex data of the IndexedBatch.

indices_block (MemoryBlock): The MemoryBlock reserved for holding indices data of the IndexedBatch.

batches (list): A list containing the active IndexedBatch objects.

free_batches (list): A list containing any currently unused batches waiting to be reused.

batch_groups (dict): Grouping of batches that share the same texture.

gameworld (object): Reference to the active gameworld, used when creating ComponentPointerAggregator to make iterating an IndexedBatch easier when rendering.

batch_count (unsigned int): The number of active batches either in use or waiting in the free list for reuse.

max_batches (unsigned int): The maximum number of batches that can be used.

frame_count (unsigned int): The number of frames that will be multibuffered for each IndexedBatch.

slots_per_block (unsigned int): The number of vertices held in each IndexedBatch.

index_slots_per_block (unsigned int): The number of indices held in each IndexedBatch. Note: OpenGL ES2 have a limit of 65,535

vbo_size_in_kb (unsigned int): The size of the batch VBO in kibibytes.

mode_str (str): The human readable mode of the rendering. Can be ‘triangles’, ‘points’, ‘line_strip’, ‘line_loop’, ‘lines’, ‘triangle_strip’, or ‘triangle_fan’.

mode (GLuint): The GL translation of the mode_str. Will be either GL_TRIANGLES, GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_TRIANGLE_STRIP, or GL_TRIANGLE_FAN.

vertex_format (KEVertexFormat): The KEVertexFormat containing information for binding the format of the vertices during rendering.

canvas (object): The canvas of the parent GameSystem that all batches will be drawn to.

system_names (list): List of the system_names that we should write pointers to in the ComponentPointerAggregator for rendering.

master_buffer (Buffer): The Buffer from which all memory will be allocated.

ent_per_batch (unsigned int): An estimation of the number of entities that will fit in each batch. The ComponentPointerAggregator will be this size per batch. Created during initialization by dividing the slots_per_block by the smallest_vertex_count init arg.