NAME

OpenGL::Sandbox::VertexArray - Object that describes an array of vertex data

VERSION

version 0.120

DESCRIPTION

A Vertex Array is an array of vertex data which can be passed to a rendering pipeline. While the concept is simple, the implementation is a mess, and has changed in each major revision of OpenGL.

The data of a Vertex Array comes from one or more Buffer objects. A Vertex Array describes how that data maps to the named vertex attributes of a Shader. For instance, texture data could be stored in one buffer object with vertex 3D coordinates stored in another, and as the shader processes each vertex it could need the first data in attributes named 's', 't', 'tx_id' and the second into a vector named 'pos'. A Vertex Array describes how to assign the next vertex to each named attribute.

In OpenGL 2.0, there was essentially just one global vertex array, and it needed overwritten (via an awkward series of function calls) each time you wanted to change the vertex data. In OpenGL 3.0, there are multiple named Vertex Array objects which can be configured once and then re-used, though it still requires awkward function calls and binding global targets. In OpenGL 4.5, you can finally set up a Vertex Array without binding anything. Here's a nice write-up on Stack Overflow.

This object attempts to represent the configuration in a version-neutral manner. There are two phases: "prepare" and "bind". On old OpenGL, prepare does nothing, since there is no way to cache the results, and bind does all the work. On new OpenGL (3.0 and up) the prepare step creates a cached VertexArray, and bind binds it. But, all you need to do is call bind and it will prepare automatically if needed.

ATTRIBUTES

name

Human-readable name of this Vertex Array (not GL's integer "name")

attributes

This is a hashref of the metadata for each attribute. You can specify it without knowing the index of an array, and that will be filled in later when it is applied to a program.

Each attribute is a hashref of:

  {
    name       => $text,   # should match the named attribute of the Program
    index      => $n,      # vertex attribute index; use undef to lookup by name
    buffer     => $buffer, # buffer this attribute comes from. Leave undef to use current buffer.
                           # This can also be a buffer ID integer.
    size       => $n,      # number of components per vertex attribute
    type       => $type,   # GL_FLOAT, GL_INT, etc.
    normalized => $bool,   # perl boolean, whether to remap ints to float [0..1)
    stride     => $ofs,    # number of bytes between stored attributes, or 0 for "tightly packed"
    pointer    => $ofs,    # byte offset into $buffer of first element, defaults to 0
  }

buffer

You can specify a buffer on each attribute, or specify it in the call to bind, or you can supply a default buffer here that will be used for all the attributes. If given a hashref, it will be inflated to a buffer object. If you give an integer, it will be used directly.

This is most useful for the following:

  my $vao= $res->new_vao({
    buffer => { data => pack('f*', @coordinates) },
    attributes => {
      position => { size => 3, type => GL_FLOAT, stride => 32 },
      normal   => { size => 3, type => GL_FLOAT, stride => 32 },
      texcoord => { size => 2, type => GL_FLOAT, stride => 32 },
    }
  });

id

For OpenGL 3.0+, this will be allocated upon demand. For earlier OpenGL, this remains undef.

has_id

Whether the ID (or lack of one) has been resolved yet.

prepared

Whether the "prepare" step has happened.

METHODS

bind

  $vertex_array->bind($program, $buffer);

Make the configuration of this vertex array active for drawing. This might cause a cascade of effects, like binding buffers, loading buffers, binding the vertex array object, looking up program attributes, and enabling and configuring the attributes. Steps which don't need repeated won't be.

If $program is not given, the current one will be used for any attribute-index lookups. If $buffer is not given, the current GL_VERTEX_ARRAY buffer will be used (unless an attribute configuration specifies otherwise).

prepare

For OpenGL 3+ this creates a Vertex Array Object (VAO) and initializes it. For earlier OpenGL, this is a no-op.

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm OpenGL::Sandbox

perl -MCPAN -e shell
install OpenGL::Sandbox