struct Gloop::Buffer

Overview

GPU-hosted storage for arbitrary data.

Most methods in this type used the "named" OpenGL functions. These utilize DSA (Direct State Access). They should be used whenever possible, but require OpenGL 4.5 or higher. If an older version of OpenGL is required, use corresponding methods in BindTarget instead.

See: https://www.khronos.org/opengl/wiki/Buffer_Object

Included Modules

Defined in:

gloop/buffer.cr
gloop/buffer/access.cr
gloop/buffer/access_mask.cr
gloop/buffer/bind_target.cr
gloop/buffer/map.cr
gloop/buffer/storage.cr
gloop/buffer/target.cr
gloop/buffer/target_map.cr
gloop/buffer/usage.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from struct Gloop::Object

context : Context context, name : Name name, none? none?, object_type object_type, to_s(io) to_s, to_unsafe : UInt32 to_unsafe

Constructor methods inherited from struct Gloop::Object

new(context : Context, name : Name) new, none(context) : self none

Instance methods inherited from module Gloop::Labelable

label : String label, label=(label : Nil)
label=(label) label=, max_label_size : Int32 max_label_size, name name, object_type object_type

Constructor Detail

def self.create(context) : self #

Creates a new buffer.

Unlike .generate, resources are created in advance instead of on the first binding.

  • OpenGL function: glCreateBuffers
  • OpenGL version: 4.5

[View source]
def self.generate(context) : self #

Generates a new buffer.

This ensures a unique name for a buffer object. Resources are not allocated for the buffer until it is bound.

See: .create

  • OpenGL function: glGenBuffers
  • OpenGL version: 2.0

[View source]

Class Method Detail

def self.copy(from read_buffer : self, to write_buffer : self, read_offset : Size, write_offset : Size, size : Size) : Nil #

Copies a subset of data from one buffer to another.

The read_offset indicates the byte offset to start copying from read_buffer. The write_offset indicates the byte offset to start copying into write_buffer. The size is the number of bytes to copy.

See: BindTarget.copy

  • OpenGL function: glCopyNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def self.delete(buffers : Enumerable(self)) : Nil #

Deletes multiple buffers.

  • OpenGL function: glDeleteBuffers
  • OpenGL version: 2.0

[View source]

Instance Method Detail

def [](start : Size, count : Size) : Bytes #

Retrieves a subset of data from the buffer.

NOTE Modifying the data returned by this method will not update the contents of the buffer.

See: BindTarget#[]

  • OpenGL function: glGetNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def [](range : Range) : Bytes #

Retrieves a range of data from the buffer.

NOTE Modifying the data returned by this method will not update the contents of the buffer.

See: BindTarget#[]

  • OpenGL function: glGetNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def []=(start : Size, count : Size, data) #

Updates a subset of the buffer's data store.

The data must have a #to_unsafe method or be a Pointer. Bytes, Slice, and StaticArray types are ideal for this.

NOTE Any length data might have is ignored. Be sure that count is less than or equal to the byte size of data.

See: BindTarget#[]=

  • OpenGL function: glNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def []=(range : Range, data) #

Updates a subset of the buffer's data store.

The data must have a #to_unsafe method or be a Pointer. Bytes, Slice, and StaticArray types are ideal for this.

NOTE Any length data might have is ignored. Be sure that the size of range is less than or equal to the byte size of data.

See: BindTarget#[]=

  • OpenGL function: glNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def allocate_data(size : Size, usage : Usage = :static_draw) : Nil #

Initializes the buffer of a given size with undefined contents.

See: BindTarget#allocate_data

  • OpenGL function: glNamedBufferData
  • OpenGL version: 4.5

[View source]
def allocate_storage(size : Size, flags : Storage) : Nil #

Initializes the buffer of a given size with undefined contents. This makes the buffer have a fixed size (immutable).

See: BindTarget#allocate_storage

  • OpenGL function: glNamedBufferStorage
  • OpenGL version: 4.5

[View source]
def bind(target : Target | BindTarget) : Nil #

Binds this buffer to the specified target.

See: BindTarget#bind

  • OpenGL function: glBindBuffer
  • OpenGL version: 2.0

[View source]
def bind(target : Target, &) : Nil #

Binds this buffer to the specified target.

The previously bound buffer (if any) is restored after the block completes.

See: BindTarget#bind

  • OpenGL function: glBindBuffer
  • OpenGL version: 2.0

[View source]
def bind(target : BindTarget, &) #

Binds this buffer to the specified target.

The previously bound buffer (if any) is restored after the block completes.

See: BindTarget#bind

  • OpenGL function: glBindBuffer
  • OpenGL version: 2.0

[View source]
def clear : Nil #

Sets the contents of the buffer to zero.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def copy_from(buffer : self, read_offset : Size, write_offset : Size, size : Size) : Nil #

Copies a subset of another buffer into this one.

The read_offset indicates the byte offset to start copying from buffer. The write_offset indicates the byte offset to start copying into this buffer. The size is the number of bytes to copy.

See: BindTarget#copy_from

  • OpenGL function: glCopyNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def copy_to(buffer : self, read_offset : Size, write_offset : Size, size : Size) : Nil #

Copies a subset of this buffer into another.

The read_offset indicates the byte offset to start copying from this buffer. The write_offset indicates the byte offset to start copying into buffer. The size is the number of bytes to copy.

See: BindTarget#copy_to

  • OpenGL function: glCopyNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def data : Bytes #

Retrieves all data in the buffer.

NOTE Modifying the data returned by this method will not update the contents of the buffer.

See: BindTarget#data

  • OpenGL function: glGetNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def data=(data) #

Stores data in this buffer.

The data must have a #to_slice method. Bytes, Slice, and StaticArray types are ideal for this. Previously set #usage hint is reapplied for this data.

See: BindTarget#data=

  • OpenGL function: glNamedBufferData
  • OpenGL version: 4.5

[View source]
def delete : Nil #

Deletes this buffer.

  • OpenGL function: glDeleteBuffers
  • OpenGL version: 2.0

[View source]
def exists? #

Checks if the buffer is known by OpenGL.

  • OpenGL function: glIsBuffer
  • OpenGL version: 2.0

[View source]
def fill(value : Int8) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : UInt8) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : Int16) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : UInt16) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : Int32) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : UInt32) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def fill(value : Float32) : Nil #

Fills the contents of the buffer to a single value.

The value is repeated throughout the buffer. Ensure the correct numerical type is used.

  • OpenGL function: glClearNamedBufferData
  • OpenGL version: 4.5

[View source]
def flush(start : Size, count : Size) : Nil #

Flushes a subset of the mapped buffer to indicate changes have been made.

See: BindTarget#flush

  • OpenGL function: glFlushMappedNamedBufferRange
  • OpenGL version: 4.5

[View source]
def flush(range : Range) : Nil #

Flushes a subset of the mapped buffer to indicate changes have been made.

See: BindTarget#flush

  • OpenGL function: glFlushMappedNamedBufferRange
  • OpenGL version: 4.5

[View source]
def flush : Nil #

Flushes the entire mapped buffer range to indicate changes have been made.

See: BindTarget#flush

  • OpenGL function: glFlushMappedNamedBufferRange
  • OpenGL version: 4.5

[View source]
def immutable? : Bool #

Indicates whether the buffer is immutable (fixed size).

See: BindTarget#immutable?

  • OpenGL function: glGetNamedBufferParameteriv
  • OpenGL enum: GL_BUFFER_IMMUTABLE_STORAGE
  • OpenGL version: 4.5

[View source]
def initialize_data(data, usage : Usage = :static_draw) : Nil #

Stores data in this buffer.

The data must have a #to_slice method. Bytes, Slice, and StaticArray types are ideal for this.

See: BindTarget#initialize_data

  • OpenGL function: glNamedBufferData
  • OpenGL version: 4.5

[View source]
def initialize_storage(data, flags : Storage) : Nil #

Stores data in this buffer. This makes the buffer have a fixed size (immutable).

The data must have a #to_slice method. Bytes, Slice, and StaticArray types are ideal for this.

See: BindTarget#initialize_storage

  • OpenGL function: glNamedBufferStorage
  • OpenGL version: 4.5

[View source]
def invalidate(start : Size, count : Size) : Nil #

Invalidates a subset of the buffer's content.

  • OpenGL function: glInvalidateBufferSubData
  • OpenGL version: 4.3

[View source]
def invalidate(range : Range) : Nil #

Invalidates a subset of the buffer's content.

  • OpenGL function: glInvalidateBufferSubData
  • OpenGL version: 4.3

[View source]
def invalidate : Nil #

Invalidates the entire content of the buffer.

  • OpenGL function: glInvalidateBufferData
  • OpenGL version: 4.3

[View source]
def map(access : AccessMask, start : Size, count : Size) : Bytes #

Maps a subset of the buffer's memory into client space.

See: BindTarget#map

  • OpenGL function: glMapNamedBufferRange
  • OpenGL version: 4.5

[View source]
def map(access : AccessMask, range : Range) : Bytes #

Maps a subset of the buffer's memory into client space.

See: BindTarget#map

  • OpenGL function: glMapNamedBufferRange
  • OpenGL version: 4.5

[View source]
def map(access : Access) : Bytes #

Maps the buffer's memory into client space.

See: BindTarget#map

  • OpenGL function: glMapNamedBuffer
  • OpenGL version: 4.5

[View source]
def map(access : AccessMask, start : Size, count : Size, & : Bytes -> _) : Bool #

Maps a subset of the buffer's memory into client space.

The buffer is automatically unmapped when the block completes. Returns false if the buffer memory was corrupted while it was mapped.

See: BindTarget#map


[View source]
def map(access : AccessMask, range : Range, & : Bytes -> _) : Bool #

Maps a subset of the buffer's memory into client space.

The buffer is automatically unmapped when the block completes. Returns false if the buffer memory was corrupted while it was mapped.

See: BindTarget#map


[View source]
def map(access : Access, & : Bytes -> _) : Bool #

Maps the buffer's memory into the client space.

The buffer is automatically unmapped when the block completes. Returns false if the buffer memory was corrupted while it was mapped.

See: BindTarget#map


[View source]
def mapped? : Bool #

Indicates whether the buffer is currently mapped.

See: BindTarget#mapped?

  • OpenGL function: glGetNamedBufferParameteriv
  • OpenGL enum: GL_BUFFER_MAPPED
  • OpenGL version: 4.5

[View source]
def mapping : Map #

Retrieves information about the buffer's current map.

Raises if the buffer isn't mapped.

See: BindTarget#mapping


[View source]
def mapping? : Map | Nil #

Retrieves information about the buffer's current map.

Returns nil if the buffer isn't mapped.

See: BindTarget#mapping?


[View source]
def object_type #

Indicates that this is a buffer object.


[View source]
def size : Int64 #

Size of the buffer's contents in bytes.

See: BindTarget#size

  • OpenGL function: glGetNamedBufferParameteri64v
  • OpenGL enum: GL_BUFFER_SIZE
  • OpenGL version: 4.5

def storage_flags : Gloop::Buffer::Storage #

Retrieves the flags previously set for the buffer's immutable storage.

See: #storage

See: BindTarget#storage_flags

  • OpenGL function: glGetNamedBufferParameteriv
  • OpenGL enum: GL_BUFFER_STORAGE_FLAGS
  • OpenGL version: 4.5

[View source]
def unmap : Bool #

Unmaps the buffer's memory from client space.

Returns false if the buffer memory was corrupted while it was mapped.

See: BindTarget#unmap

  • OpenGL function: glUnmapNamedBuffer
  • OpenGL version: 4.5

[View source]
def update(offset : Size, data) : self #

Updates a subset of the buffer's data store.

The number of bytes updated in the buffer is equal to the byte size of data. The data must have a #to_slice. Bytes, Slice, and StaticArray types are ideal for this.

See: BindTarget#update

  • OpenGL function: glNamedBufferSubData
  • OpenGL version: 4.5

[View source]
def usage : Gloop::Buffer::Usage #

Retrieves the usage hints previously provided for the buffer's data.

See: #data

See: BindTarget#usage

  • OpenGL function: glGetNamedBufferParameteriv
  • OpenGL enum: GL_BUFFER_USAGE
  • OpenGL version: 4.5

[View source]