Primitive Building

This section explains the functions used to create custom primitives.

GameMaker: Studio permits you to define your own custom primitives following the specifications of the vertex format that you have chosen (see Vertex Formats). These can then be used within any shaders that you have created.

The Vertex Buffer

Any primitives that you build are held in a vertex buffer. This must be created beforehand and then referenced by the functions that are used to build your primitive. The vertex buffer can be re-used as many times as necessary to create different primitives, or it can be "frozen" to maintain a specific primitive type for the duration of your game or level (which is the fastest approach, so if you know that a primitive you build will not change then you should always use this option).

The following functions are available for the vertex buffer:

  1. vertex_create_buffer
  2. vertex_create_buffer_ext
  3. vertex_create_buffer_from_buffer
  4. vertex_create_buffer_from_buffer_ext
  5. vertex_get_buffer_size
  6. vertex_get_number
  7. vertex_delete_buffer

Building A Primitive

The primitives that you build should follow the format that you have set using the Vertex Formats functions, so if you have defined a vertex format with only positional data, there is no point building your primitive with colour data. You should note that the order in which you add properties to the primitive you are building is defined by the order in which you added these properties when creating the vertex format, so if you have defined the vector format with the order position, colour and texture coordinate, you must add these properties to the primitive being built in the same order otherwise you will get errors.

An example of a single triangle primitive being built is shown in the following code:

v_buff = vertex_create_buffer();
vertex_begin(v_buff, global.my_format);
vertex_position(v_buff, 10, 10);
vertex_colour(v_buff, c_white, 1);
vertex_texcoord(v_buff, 0, 0);
vertex_position(v_buff, 110, 10);
vertex_colour(v_buff, c_white, 1);
vertex_texcoord(v_buff, 1, 0);
vertex_position(v_buff, 110, 110);
vertex_colour(v_buff, c_white, 1);
vertex_texcoord(v_buff, 1, 1);
vertex_end(v_buff);
var tex = background_get_texture(background1);
shader_set(shader_prim);
vertex_submit(v_buff, pr_trianglelist, tex);
shader_reset();

Primitives can be points, line lists or strips, or triangle lists or strips, but you are not permitted triangle fans since most mobile hardware will not accept that primitive type. The constants used to define these different primitive types can be found here.

NOTE: You can build the primitive and store it in the vertex buffer in any step of your game, however to draw it, you must submit it during the Draw Event.

The following functions are available for building primitives:

  1. vertex_begin
  2. vertex_colour
  3. vertex_normal
  4. vertex_position
  5. vertex_position_3d
  6. vertex_argb
  7. vertex_texcoord
  8. vertex_float1
  9. vertex_float2
  10. vertex_float3
  11. vertex_float4
  12. vertex_ubyte4
  13. vertex_end
  14. vertex_freeze
  15. vertex_submit


Back: Shaders
Next: Vertex Formats
© Copyright YoYo Games Ltd. 2015 All Rights Reserved