Module Lit.Buf

module Buf: sig .. end
Buffers.

Buffers are linear arrays of scalars of a given scalar type. At a given point in time the scalars may exist only on the CPU side, only on the GPU side or on both sides (synchronized or not).



Buffer usage


type usage = [ `Dynamic_copy
| `Dynamic_draw
| `Dynamic_read
| `Static_copy
| `Static_draw
| `Static_read
| `Stream_copy
| `Stream_draw
| `Stream_read ]
The type for buffer usage hints. First part of the name identifies the data access pattern: Second part of the name distinguishes the data flow:
val pp_usage : Format.formatter -> usage -> unit
pp_usage ppf usage prints an uspecified representation of usage on ppf.

Buffers


type ('a, 'b) init = [ `Cpu of Gg.Ba.scalar_type * int
| `Float16 of (int, Bigarray.int16_unsigned_elt) Gg.bigarray
| `Float32 of (float, Bigarray.float32_elt) Gg.bigarray
| `Float64 of (float, Bigarray.float64_elt) Gg.bigarray
| `Gpu of Gg.Ba.scalar_type * int
| `Int16 of (int, Bigarray.int16_signed_elt) Gg.bigarray
| `Int32 of (int32, Bigarray.int32_elt) Gg.bigarray
| `Int64 of (int64, Bigarray.int64_elt) Gg.bigarray
| `Int8 of (int, Bigarray.int8_signed_elt) Gg.bigarray
| `UInt16 of (int, Bigarray.int16_unsigned_elt) Gg.bigarray
| `UInt32 of (int32, Bigarray.int32_elt) Gg.bigarray
| `UInt64 of (int64, Bigarray.int64_elt) Gg.bigarray
| `UInt8 of (int, Bigarray.int8_unsigned_elt) Gg.bigarray ]
The type for buffer data initialisation.
type t = Lit.buf 
The type for buffers.
val create : ?cpu_autorelease:bool ->
?usage:usage -> ('a, 'b) init -> Lit.buf
create cpu_autorelease usage init is a buffer value such that:

Note that while CPU and GPU buffer length may change, their scalar type is immutable.

At creation time Lit.Buf.gpu_upload is true this means that the GPU buffer will be automatically created the first time the buffer is used.

val usage : Lit.buf -> usage
usage b is the usage of b.
val scalar_type : Lit.buf -> Gg.Ba.scalar_type
scalar_type b is the scalar type of b.
val pp : Format.formatter -> Lit.buf -> unit
pp ppf b prints an unspecified representation of b on ppf.

GPU buffer


val gpu_count : Lit.buf -> int
gpu_count b is the number of scalars in the GPU buffer of b.
val gpu_exists : Lit.buf -> bool
gpu_exists b is true if the GPU buffer of b exists.
val gpu_upload : Lit.buf -> bool
gpu_upload b is true if the CPU scalars will uploaded to the GPU next time the renderer uses the buffer.
val set_gpu_upload : Lit.buf -> bool -> unit
set_gpu_upload b u if u is true sets b to upload its CPU buffer to the GPU buffer next time the renderer sees the buffer.

Warning If Lit.Buf.cpu is None at the time of upload this will zero any existing data on the GPU buffer.

val sync_gpu_to_cpu : Lit.renderer -> Lit.buf -> unit
gpu_to_cpu r b reads back b's GPU buffer into b's CPU buffer. A CPU buffer is created in none existed yet or if the size of the CPU buffer is different from the size of the GPU buffer.
Raises Invalid_argument if Lit.Buf.gpu_exists is false.

Mapping the GPU buffer in CPU


val gpu_map : Lit.renderer ->
[ `R | `RW | `W ] ->
Lit.buf -> ('a, 'b) Gg.Ba.ba_scalar_type -> ('a, 'b) Gg.bigarray
gpu_map r access b st maps the GPU buffer of b with access access.

Warning. A mapped buffer cannot be used in a render operation, you need to unmap it first. Once unmapped the bigarray becomes invalid. Don't try to access it, it may result in program termination.
Raises Invalid_argument if st does not match buf's scalar type.

val gpu_unmap : Lit.renderer -> Lit.buf -> unit
gpu_unmap r b unmaps the buffer b.

Warning. This invalidates the memory pointed to by the bigarray returned by Lit.Buf.gpu_map or gpu_map_buffer, do not try to access it after this function has been called it may result in program termination.


CPU buffer


val cpu_count : Lit.buf -> int
cpu_count b is the number of scalars in the CPU buffer of b.
val cpu_exists : Lit.buf -> bool
cpu_exists b is true if the CPU buffer of b exists.
val cpu : Lit.buf -> ('a, 'b) Gg.Ba.ba_scalar_type -> ('a, 'b) Gg.bigarray option
cpu b st is the CPU buffer of b (if any).

Note. If you want changes you made to the buffer to be picked up by the GPU side buffer you must call Lit.Buf.set_gpu_upload.
Raises Invalid_argument if scalar type st is not the scalar type of b.

val cpu_buffer : Lit.buf -> Gg.buffer option
cpu_buffer is like Lit.Buf.cpu but returns a Gg.buffer value.
val get_cpu : Lit.buf -> ('a, 'b) Gg.Ba.ba_scalar_type -> ('a, 'b) Gg.bigarray
get_cpu b st is cpu b st but raises if there's no cpu buffer.
Raises Invalid_argument if cpu b st raises or if cpu_exists b is false.
val get_cpu_buffer : Lit.buf -> Gg.buffer
get_cpu_buffer is like Lit.Buf.get_cpu but returns a Gg.buffer value
val set_cpu : Lit.buf -> ('a, 'b) Gg.bigarray option -> unit
set_cpu b ba sets the CPU buffer of b to ba.

Note. If you want changes to the scalars to be picked up by the GPU side buffer you must call Lit.Buf.set_gpu_upload.
Raises Invalid_argument if the bigarray kind of b is not compatible with the scalar type of b.

val set_cpu_buffer : Lit.buf -> Gg.buffer option -> unit
set_cpu_buffer is like Lit.Buf.set_cpu but uses a Gg.buffer value.
val cpu_autorelease : Lit.buf -> bool
cpu_autorelease buf is true if the CPU buffer is set to None once uploaded to the GPU.
val set_cpu_autorelease : Lit.buf -> bool -> unit
set_cpu_autorelease b bool sets the autorelease behaviour to bool.
val sync_cpu_to_gpu : Lit.renderer -> Lit.buf -> unit
sync_cpu_to_gpu r b uploads the CPU buffer of b to the GPU buffer. A GPU buffer is created if none existed yet.
Raises Invalid_argument if Lit.Buf.cpu_exists is false.