vertex_submit_ext

This function submits a range of vertices in the given vertex buffer to the GPU for drawing.

The range is provided as an offset and number of vertices to submit. The offset can be any value greater than 0, the number of vertices the actual number to submit, or the value -1 to indicate that all vertices starting at the offset should be submitted.

Usage Notes

• This function can only be used in the Draw Events.
• The function supports both regular and frozen vertex buffers.
• The number of vertices must be in accordance with the primitive type you're drawing.
• You can use vertex_submit if you need to submit the entire vertex buffer.
• Triangle fans (pr_trianglefan) are converted to pr_trianglelist internally on platforms that don't support them when you call this function.

Syntax:

vertex_submit_ext(buffer, primtype, texture, offset, number);

Returns:

N/A

Example 1: Basic Use

Draw Event

 vertex_submit_ext(vb, pr_trianglelist, -1, 5, 6);

The above code shows a basic call to the function vertex_submit_ext. The number of vertices is 6, which is a multiple of 3, as required for the primitive type used pr_trianglelist.

Example 2: Progressively Drawing a Line

Create Event

vb = vertex_create_buffer();
vertex_begin(vb, fmt_default);
repeat(100)
{
    vertex_position_3d(vb, random(room_width), random(room_height), 0);
    vertex_color(vb, c_white, 1);
    vertex_texcoord(vb, 0, 0);
}
vertex_end(vb);

Draw Event

var _num = (current_time / 1000 * 12) mod (vertex_get_number(vb) + 1);
vertex_submit_ext(vb, pr_linestrip, -1, 0, _num);

The code example above fills a vertex buffer with 100 random points and then progressively draws more points using the value of the built-in variable current_time.

In the Create event, a vertex buffer is created using vertex_create_buffer. 100 vertices are then added to it in a repeat loop. Every vertex gets a random position in the room, a white colour and a texture coordinate that's unused but must be there, according to the passthrough_vertex_format used.

In the Draw event, the vertex buffer is submitted using vertex_submit_ext as a pr_linestrip. The starting vertex is always the first one (indicated by the offset value 0), the number of vertices is calculated using current_time with a modulo operator used to create a simple animation that loops.

Example 3: Groups of Vertices

Create Event

vb = vertex_create_buffer();
arr_groups = [];

var _px, _py, _col;
vertex_begin(vb, fmt_default);
for(var i = 0;i < 8;i++)
{
    _px = random(room_width);
    _py = random(room_height);
    _col = choose(c_red, c_blue, c_green, c_yellow);
    repeat(3)
    {
        vertex_position_3d(vb, _px + random_range(-20, 20), _py + random_range(-20, 20), 0);
        vertex_color(vb, _col, 1);
        vertex_texcoord(vb, 0, 0);
    }
    array_push(arr_groups, {visible: true, range: {offset: i * 3, num: 3}});
}
vertex_end(vb);
vertex_freeze(vb);

Draw Event

var i = 0, _num = array_length(arr_groups);
repeat(_num)
{
    var _group = arr_groups[i++];
    if (!_group.visible) { continue; }
    vertex_submit_ext(vb, pr_trianglelist, -1, _group.range.offset, _group.range.num);
}

The code example above shows how to treat a vertex buffer as groups of vertices, each given by a range and number of vertices. The visibility of every group of vertices can be set separately.

In the Create event, a vertex buffer is created and an empty array with it to store info about every range of vertices. A total of 8 triangles are added to the vertex buffer using the default passthrough_vertex_format, each with a random position somewhere in the room, a random colour and a random width and height. A struct is also pushed onto the array using array_push that stores the visibility and range of the vertices of each triangle. Finally the vertex buffer is frozen with vertex_freeze so it can be submitted to the GPU faster.

In the Draw event, all groups of vertices are submitted separately with a call to vertex_submit_ext inside a repeat loop. If any group is not visible, it is skipped and the next one is checked.