NAME

OpenGL::Sandbox::Buffer - Wrapper object for OpenGL Buffer Object

VERSION

version 0.110

DESCRIPTION

OpenGL Buffers represent a named block of memory on the graphics hardware which can be used for various purposes, mostly serving to deliver large quantities of data from the application to be used repeatedly by the shaders.

Creating a buffer simply reserves an ID, which can then later be bound to a buffer target and loaded with data.

Loading this module requires OpenGL 2.0 or higher.

ATTRIBUTES

name

Human-readable name of object (not GL's integer "name")

target

OpenGL buffer target which this buffer object should be bound to, when necessary. This attribute will be updated by "bind" if you bind to a different target.

usage

Default data usage hint for OpenGL, when loading data into this buffer. If this is undef, the default when loading data will be GL_STATIC_DRAW. If you call load with a different usage value, it will update this attribute.

id

The OpenGL integer "name" of this buffer. This is a lazy-built attribute, and will call glGenBuffers the first time you access it. Use has_id to find out whether this has happened yet.

has_id

True if the id attribute is allocated.

autoload

If this field is defined at the time of the next call to "bind", this data will be immediately be loaded into the buffer with glBufferData. The field will then be cleared, to avoid holding onto large blobs of data.

filename

If passed to the constructor, this implies an "autoload" from the file. Else it is just for informational purposes.

METHODS

new

This is a standard Moo constructor, accepting any of the attributes, however it also accepts an alias 'data' for the "autoload" attribute.

bind

  $buffer->bind;
  $buffer->bind(GL_ARRAY_BUFFER);

Bind this buffer to a target, using "target" as the default. If autoload is set, this will also load that data into the buffer.

Returns $self for convenient chaining.

load

  $buffer->load( $data, $usage_hint );

Load data into this buffer object. You may pass a scalar, scalar ref, memory map (which is just a special scalar ref) or an OpenGL::Array. This performs an automatic glBindBuffer to the value of "target". If "target" is not defined, this dies.

load_at

  $buffer->load_at( $offset, $data );
  $buffer->load_at( $offset, $data, $src_offset, $src_length );

Load some data into the buffer at an offset. If the $src_offset and/or $src_length values are given, this will use a substring of $data. The buffer will be bound to "target" first, if it wasn't already. This performs an automatic glBindBuffer to the value of "target". If "target" is not defined, this dies. Additionally, if "load" has not been called before this dies.

Returns $self for convenient chaining.

mmap

  my $mmap= $buffer->mmap($mode);
  my $mmap= $buffer->mmap($mode, $offset, $length);

Call glMapBuffer (or glMapNamedBuffer) to memory-map the buffer into the current process. The $mode can be a GL constant of GL_READ_ONLY, GL_WRITE_ONLY, GL_READ_WRITE or a perl style mode of r, w, r+.

On OpenGL < 4.5, the buffer gets automatically mapped to its "target" to perform the mapping. OpenGL 4.5 introduced glMapNamedBuffer which avoids the need for binding.

The memory-map object persists for the live of this buffer object or until you call unmap. Until then, mmap acts as an attribute to return the previous value to you.

unmap

Release a memory-mapping of this buffer, if any. If OpenGL < 4.5, this forces the buffer to get mapped first. This happens automatically on object destruction. If automatically destroyed on OpenGL < 4.5, it genertes a warning, since messing with global state during object destruction is a bad thing.

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