NAME

OpenGL::Sandbox::VertexArray - Object that encapsulates the mapping from buffer to vertex shader

VERSION

version 0.110

DESCRIPTION

Vertex Arrays can be hard to grasp, since their implementation has changed in each major version of OpenGL, but I found a very nice write-up in the accepted answer of:

https://stackoverflow.com/questions/21652546/what-is-the-role-of-glbindvertexarrays-vs-glbindbuffer-and-what-is-their-relatio

In short, there needs to be something to indicate which bytes of the buffer map to which vertex attributes as used in the shader. The shader can declare anything attributes it wants, and the buffer(s) need to contain matching arrangement of data. This configuration is called a "VertexArray" (who names these things??)

The oldest versions of OpenGL require this information to be applied on each buffer change. The newer versions can cache the configuration in an Object, and the newest versions of OpenGL can set it up without mucking around with global state.

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. All you need to do is call bind and it will prepare 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 VertexArrayObject 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