SortVisuals

View source
ceramic.SortVisuals (Class)

High-performance stable merge sort implementation specifically optimized for Visual arrays.

SortVisuals provides a specialized sorting algorithm for rendering order in Ceramic. It implements a stable merge sort that preserves the relative order of visuals with equal sorting criteria, which is crucial for consistent rendering behavior across all platforms.

The sorting criteria hierarchy:

  1. Invisible/untouchable visuals are sorted first (behind everything)
  2. Render target priority (higher priority renders on top)
  3. Depth value (higher depth renders on top)
  4. For Quads/Meshes with same depth:
    • Texture index (lower index renders on top for batching efficiency)
    • Blending mode (for draw call batching)

This implementation is heavily optimized:

  • All methods are inlined for maximum performance
  • Uses unsafe array access to avoid bounds checking
  • Switches to insertion sort for small arrays (< 12 elements)
  • Custom comparison function optimized for Visual properties

Example usage:

var visuals:Array<Visual> = [...];
SortVisuals.sort(visuals); // Sorts in place

Note: This class is used internally by the rendering system and typically doesn't need to be called directly unless implementing custom rendering logic.

Based on Haxe's stable sort implementation with Visual-specific optimizations.

See: ceramic.Visual For the visual hierarchy, ceramic.SortVisualsByDepth For depth-only sorting

Static Members

sort(a: Array<Visual>): Void

Sorts an array of Visual objects in place for optimal rendering order.

This operation modifies the input array directly. The sort is stable, meaning visuals with equal sorting criteria maintain their relative order. This is important for predictable rendering when multiple visuals have the same depth and properties.

The algorithm automatically chooses between merge sort for larger arrays and insertion sort for small arrays (< 12 elements) for optimal performance.

Name Type Description
a Array<Visual> The array of visuals to sort. Modified in place. If null, behavior is undefined.

Private Members

cmp(a: Visual, b: Visual): Int

Compares two visuals for rendering order.

Name Type Description
a Visual First visual to compare
b Visual Second visual to compare
Returns Description
Int -1 if a should render before b, 1 if b should render before a, 0 if equal
rec(a: Array<Visual>, from: Int, to: Int): Void
Name Type
a Array<Visual>
from Int
to Int
doMerge(a: Array<Visual>, from: Int, pivot: Int, to: Int, len1: Int, len2: Int): Void
Name Type
a Array<Visual>
from Int
pivot Int
to Int
len1 Int
len2 Int
rotate(a: Array<Visual>, from: Int, mid: Int, to: Int): Void
Name Type
a Array<Visual>
from Int
mid Int
to Int
gcd(m: Int, n: Int): Int
Name Type
m Int
n Int
Returns
Int
upper(a: Array<Visual>, from: Int, to: Int, val: Int): Int
Name Type
a Array<Visual>
from Int
to Int
val Int
Returns
Int
lower(a: Array<Visual>, from: Int, to: Int, val: Int): Int
Name Type
a Array<Visual>
from Int
to Int
val Int
Returns
Int
swap(a: Array<Visual>, i: Int, j: Int): Void
Name Type
a Array<Visual>
i Int
j Int
compare(a: Array<Visual>, i: Int, j: Int): Int
Name Type
a Array<Visual>
i Int
j Int
Returns
Int