Class ScrollTextBuffer

A fixed-capacity ring buffer for storing text lines with pixel-height caching, designed for smooth pixel-based scrolling with accurate TMP measurement integration.

Inheritance
object
ScrollTextBuffer
Inherited Members
Namespace: Scylla.Core.Util.UI
Assembly: ScyllaCore.dll
Syntax
public sealed class ScrollTextBuffer
Remarks

Key design properties: the buffer has a fixed capacity; when full, the oldest lines are evicted automatically. Each line's pixel height is cached, and a parallel cumulative height array enables O(log n) binary search to locate the line at any pixel offset. Height measurement uses a live TMP component for accurate results that account for multi-line wrapping; a character-width estimation fallback is used when no measurement component is available.

Use ScrollPhysics as the companion class for iOS-style smooth pixel-level scrolling driven by the content height reported by this buffer.

Constructors

ScrollTextBuffer(int)

Creates a new ScrollTextBuffer with the specified capacity.

Declaration
public ScrollTextBuffer(int capacity = 1000)
Parameters
Type Name Description
int capacity

Maximum number of lines to store.

Fields

DEFAULT_CAPACITY

Default buffer capacity (number of lines).

Declaration
public const int DEFAULT_CAPACITY = 1000
Field Value
Type Description
int

DEFAULT_LINE_HEIGHT

Default line height in pixels when no measurement is available.

Declaration
public const float DEFAULT_LINE_HEIGHT = 20
Field Value
Type Description
float

MAX_CAPACITY

Maximum allowed buffer capacity.

Declaration
public const int MAX_CAPACITY = 100000
Field Value
Type Description
int

MIN_CAPACITY

Minimum allowed buffer capacity.

Declaration
public const int MIN_CAPACITY = 1
Field Value
Type Description
int

Properties

AutoScroll

Gets whether auto-scroll is enabled (automatically scroll to bottom on new content).

Declaration
public bool AutoScroll { get; set; }
Property Value
Type Description
bool

Capacity

Gets the fixed capacity of this buffer (maximum number of lines).

Declaration
public int Capacity { get; }
Property Value
Type Description
int

DisplayWidth

Gets the current display width used for height calculations.

Declaration
public float DisplayWidth { get; }
Property Value
Type Description
float

Font

Gets the current font used for height calculations.

Declaration
public TMP_FontAsset Font { get; }
Property Value
Type Description
TMP_FontAsset

FontSize

Gets the current font size used for height calculations.

Declaration
public float FontSize { get; }
Property Value
Type Description
float

IsEmpty

Gets whether the buffer is empty.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
bool

LineCount

Gets the current number of lines in the buffer.

Declaration
public int LineCount { get; }
Property Value
Type Description
int

LineHeight

Gets the current line height in pixels.

Declaration
public float LineHeight { get; }
Property Value
Type Description
float

NeedsRefresh

Gets whether the height cache is dirty and a re-render is required. Callers can check this before calling Update or querying pixel offsets to determine whether layout and rendering must be refreshed this frame.

Declaration
public bool NeedsRefresh { get; }
Property Value
Type Description
bool

TotalContentHeight

Gets the total pixel height of all lines in the buffer combined. Lazily triggers a height cache recalculation if the cache is dirty before returning the value.

Declaration
public float TotalContentHeight { get; }
Property Value
Type Description
float

Methods

AddLine(string)

Adds a line of text to the buffer. Trailing newline characters are stripped before the line is stored.

Declaration
public void AddLine(string text)
Parameters
Type Name Description
string text

The text to add. null is treated as an empty string.
Remarks

Trailing newlines are stripped because lines are later concatenated using AppendLine() for TMP display. A trailing newline in the stored text would create an unwanted blank gap between lines in the rendered output. Stripping ensures each logical line occupies exactly its measured pixel height.

AddLines(IEnumerable<string>)

Adds multiple lines of text to the buffer. A null collection is silently ignored. Individual null entries within the collection are treated as empty strings.

Declaration
public void AddLines(IEnumerable<string> lines)
Parameters
Type Name Description
IEnumerable<string> lines

The lines to add. May be null.

Clear()

Clears all lines from the buffer.

Declaration
public void Clear()

CreateBuilder()

Creates a new builder for configuring a ScrollTextBuffer.

Declaration
public static ScrollTextBuffer.Builder CreateBuilder()
Returns
Type Description
ScrollTextBuffer.Builder

A new builder instance.

FindLineAtPixelOffset(float)

Finds the line index at a specific pixel offset from the top of the content. Uses binary search for O(log n) performance.

Declaration
public int FindLineAtPixelOffset(float pixelOffset)
Parameters
Type Name Description
float pixelOffset

The pixel offset from the top of the content.
Returns
Type Description
int

The index of the line that occupies the given pixel offset. Returns 0 if pixelOffset is 0 or negative. Returns the last line index if pixelOffset equals or exceeds the total content height. Returns -1 only if the buffer is empty.

ForceLineHeightUpdate()

Forces the line height to be recalculated from the measurement component. Call this when line spacing changes on the measurement component.

Declaration
public void ForceLineHeightUpdate()

GetAllText()

Gets the combined text of all lines in the buffer, from oldest to newest. Lines are joined using platform-neutral line separators via StringBuilder.AppendLine().

Declaration
public string GetAllText()
Returns
Type Description
string

The combined text of all lines, or string.Empty if the buffer is empty.

GetCumulativeHeight(int)

Gets the cumulative height from line 0 to the specified line (inclusive).

Declaration
public float GetCumulativeHeight(int index)
Parameters
Type Name Description
int index

The line index.
Returns
Type Description
float

The cumulative height in pixels.

GetLine(int)

Gets a line by index, where index 0 is the oldest surviving line in the buffer. After the ring buffer has wrapped, index 0 is the oldest line that has not yet been evicted, not necessarily the first line ever added.

Declaration
public ScrollTextBuffer.ScrollTextLine GetLine(int index)
Parameters
Type Name Description
int index

The line index (0 = oldest surviving line).
Returns
Type Description
ScrollTextBuffer.ScrollTextLine

The line at the specified index.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when index is out of range.

GetLineHeight(int)

Gets the pixel height of a specific line.

Declaration
public float GetLineHeight(int index)
Parameters
Type Name Description
int index

The line index.
Returns
Type Description
float

The height in pixels.

GetPixelOffsetForLine(int)

Gets the Y pixel coordinate of the top edge of the specified line, measured from the top of the total content area. This equals the cumulative height of all preceding lines.

Declaration
public float GetPixelOffsetForLine(int lineIndex)
Parameters
Type Name Description
int lineIndex

The line index.
Returns
Type Description
float

The pixel offset of the top edge of the specified line. Returns 0 when lineIndex is 0 or negative. Returns TotalContentHeight when lineIndex is equal to or greater than LineCount.

GetVisibleLines(float, float)

Gets the visible lines within a pixel range, using a cached array to avoid GC allocations.

Declaration
public ScrollTextLineView[] GetVisibleLines(float startPixel, float endPixel)
Parameters
Type Name Description
float startPixel

Start pixel offset from the top of the content.
float endPixel

End pixel offset from the top of the content.
Returns
Type Description
ScrollTextLineView[]

An array of visible lines with their pixel positions, sized exactly to the visible count. The returned array is a cached internal array reused across calls. Callers must not hold a reference to it beyond the current frame or render iteration, as it may be overwritten on the next call when a different number of lines is visible.

GetVisibleText(float, float)

Gets the combined text of visible lines within a pixel range.

Declaration
public string GetVisibleText(float startPixel, float endPixel)
Parameters
Type Name Description
float startPixel

Start pixel offset from top.
float endPixel

End pixel offset from top.
Returns
Type Description
string

The combined visible text.

InvalidateHeightCache()

Forces a recalculation of all height caches.

Declaration
public void InvalidateHeightCache()

SetDisplayMetrics(float, TMP_FontAsset, float)

Sets the display metrics used for line height calculation. Changing any metric invalidates the full height cache; the cache is rebuilt lazily on the next access to TotalContentHeight or pixel-offset queries.

Declaration
public void SetDisplayMetrics(float displayWidth, TMP_FontAsset font, float fontSize)
Parameters
Type Name Description
float displayWidth

The available width for text display in pixels. Clamped to [1, 16384].
TMP_FontAsset font

The TMP font asset.
float fontSize

The font size in points. Clamped to [1, 1000].

SetEventPublishing(bool)

Enables or disables event publishing.

Declaration
public void SetEventPublishing(bool enabled)
Parameters
Type Name Description
bool enabled

Whether to publish events.

SetLineHeight(float)

Sets the line height directly (overrides font-calculated value).

Declaration
public void SetLineHeight(float lineHeight)
Parameters
Type Name Description
float lineHeight

The line height in pixels.

SetMeasurementComponent(TMP_Text)

Sets the TMP component used for accurate pixel height measurement. When set, the buffer uses TMPUtil.GetWrappedLineCount against this component to determine the exact number of visual lines for each stored line, then multiplies by LineHeight to obtain the pixel height.

Declaration
public void SetMeasurementComponent(TMP_Text measurementComponent)
Parameters
Type Name Description
TMP_Text measurementComponent

The TMP component to use for measurement. Pass null to fall back to EstimateLineHeight, which approximates height from average character width. The estimation fallback is less accurate, particularly for proportional-width fonts where character widths vary significantly.

TryGetLine(int, out ScrollTextLine)

Attempts to get a line by index.

Declaration
public bool TryGetLine(int index, out ScrollTextBuffer.ScrollTextLine line)
Parameters
Type Name Description
int index

The line index (0 = oldest).
ScrollTextBuffer.ScrollTextLine line

The line if found.
Returns
Type Description
bool

True if the line was found.

Extension Methods