Skip to content

ColorBuffer

Inherits: RefCounted
Namespace: TauPlot

Ring buffer that stores Color values with a fixed capacity.

Description

ColorBuffer stores a sequence of Color values in a ring buffer of fixed capacity. When the buffer is full, appending a new value drops the oldest one.

All read and write operations use logical indices. Index 0 refers to the oldest value currently in the buffer. Index size()- 1 refers to the most recently appended one. Logical indices shift when the buffer wraps: after a new value is appended into a full buffer, every index decreases by one.

The buffer is pre-allocated at construction and does not resize unless set_capacity() is called explicitly.

Example

# Ring buffer with a capacity of 128 colors.
var colors := TauPlot.ColorBuffer.new(128)

# Append one color.
colors.append_value(Color.RED)

Notes

  1. Default value fills unused slots. At construction and after clear(), every slot is filled with p_default_value. The default for p_default_value is NO_COLOR (Color(0, 0, 0, 0)), which is fully transparent black.

  2. Out-of-range access logs an error. get_value(), set_value(), and set_values() log an error and return early when the buffer is empty or the index is out of range.

  3. append_value() and append_values() always succeed. They never reject input. When the buffer is full, the oldest value is silently overwritten. The return value indicates how many existing values were overwritten.

Constructor

new()

ColorBuffer.new(p_capacity: int) -> ColorBuffer

Creates an empty buffer with the given capacity. The buffer is ready to use immediately after construction.

Parameters

  • p_capacity: int Maximum number of Color values the buffer can hold. Values below 1 are clamped to 1.
  • p_default_value: Color Value used to fill unused slots at construction and after clear(). Default: NO_COLOR (Color(0, 0, 0, 0)).

Methods

Introspection

get_capacity()

get_capacity() -> int

Returns the maximum number of values the buffer can hold.

size()

size() -> int

Returns the number of values currently stored. Always between 0 and get_capacity().

Reading and writing individual values

get_value()

get_value(p_logical_index: int) -> Color

Returns the Color at the given logical index. Index 0 is the oldest value in the buffer, size()- 1 is the most recent. Logs an error and returns Color(0, 0, 0, 0) if the buffer is empty or the index is out of range.

Parameters

  • p_logical_index: int Logical index in the range [0,size()- 1].

set_value()

set_value(p_logical_index: int, p_value: Color) -> void

Overwrites the Color at the given logical index. Index 0 is the oldest value, size()- 1 is the most recent. Logs an error and does nothing if the buffer is empty or the index is out of range.

Parameters

  • p_logical_index: int Logical index in the range [0,size()- 1].
  • p_value: Color Replacement value.

set_values()

set_values(p_start_index: int, p_values: PackedColorArray) -> int

Overwrites a contiguous range of values starting at p_start_index. Writes as many values as fit from p_start_index to the end of the currently stored range. Returns the number of values actually written. Returns 0 without writing if p_values is empty, the buffer is empty, or p_start_index is out of range. Logs an error in the latter two cases.

Parameters

  • p_start_index: int Logical index of the first slot to overwrite. Must be in the range [0,size()- 1].
  • p_values: PackedColorArray Replacement values. Values beyond size()- p_start_index are ignored.

Appending values

append_value()

append_value(p_value: Color) -> int

Appends one Color to the buffer. If the buffer is full, the oldest value is overwritten. Returns 1 if an existing value was overwritten, 0 otherwise.

Parameters

  • p_value: Color Value to append.

append_values()

append_values(p_values: PackedColorArray) -> int

Appends multiple Color values to the buffer. If the buffer does not have enough free slots, the oldest values are overwritten. Returns the number of existing values overwritten. Returns 0 immediately if p_values is empty.

Parameters

  • p_values: PackedColorArray Values to append, in order from oldest to newest.

Capacity

set_capacity()

set_capacity(p_capacity: int) -> void

Resizes the buffer to the new capacity. Values below 1 are clamped to 1. If the new capacity is smaller than the current sample count, the oldest values are dropped. If the new capacity is greater, existing values are preserved, new slots are pre-filled with the default value set at construction, and size() is unchanged. Does nothing if the new capacity equals the current one.

Parameters

  • p_capacity: int New maximum number of values the buffer can hold.

Clearing data

clear()

clear() -> void

Removes all stored values. The buffer capacity is unchanged. All slots are refilled with the p_default_value set at construction.

  • Float32Buffer Sibling ring buffer storing float values (32-bit).
  • Float64Buffer Sibling ring buffer storing float values (64-bit).
  • Int32Buffer Sibling ring buffer storing int values (32-bit).
  • StringBuffer Sibling ring buffer storing String values.