NAME
OpenGL::Sandbox::Buffer - Wrapper object for OpenGL Buffer Object
VERSION
version 0.120
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.