Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ProwlEngine/Prowl.Paper/llms.txt

Use this file to discover all available pages before exploring further.

The Paper class is the root object for every Prowl.Paper UI session. You create one instance per viewport, feed it a renderer and dimensions, then call BeginFrame and EndFrame around your immediate-mode draw code each tick. Everything else — elements, animations, input, styles — hangs off this single object.

​
Constructor

public Paper(ICanvasRenderer renderer, float width, float height, FontAtlasSettings fontAtlas)
Initializes a Paper instance and allocates all internal subsystems: the element pool, canvas, input tables, and root element.
​
renderer
ICanvasRenderer
required
The backend canvas renderer that Paper will issue draw calls to. Implement ICanvasRenderer in your host project to bridge Paper to any graphics API.
​
width
float
required
Initial viewport width in logical (CSS-style) pixels.
​
height
float
required
Initial viewport height in logical pixels.
​
fontAtlas
FontAtlasSettings
required
Settings used by the internal Canvas to rasterize font glyphs. Includes atlas size and default font.

​
Frame Loop

Every frame you must bracket your UI code with BeginFrame and EndFrame. Input feed calls go before BeginFrame; element and style calls go between the two.
1

Feed input

Call SetPointerPosition, SetKeyState, etc. to push host events into Paper.
2

BeginFrame

Resets the element hierarchy, advances timing, and opens a new canvas frame.
3

Build UI

Call Box, Row, Column, animation helpers, style setters, and anything else that describes your layout.
4

EndFrame

Runs layout, handles interaction, renders all elements, and flushes the canvas to the renderer.

​
BeginFrame

public void BeginFrame(float deltaTime, float dpiScale = 1.0f)
​
deltaTime
float
required
Elapsed seconds since the previous frame. Used to advance Time, DeltaTime, and all animation state.
​
dpiScale
float
default:"1.0"
When greater than 0, sets DisplayFramebufferScale to (dpiScale, dpiScale) for this frame. Pass 0 or a negative value to leave DisplayFramebufferScale untouched (useful if you set it manually before the call).

​
EndFrame

public void EndFrame()
No parameters. Executes in order:
  1. Updates all element style transitions.
  2. Fires OnEndOfFramePreLayout, then runs the layout pass.
  3. Fires OnEndOfFramePostLayout.
  4. Calls post-layout callbacks recursively.
  5. Performs hit-testing and interaction handling.
  6. Renders the element tree (respecting layer ordering).
  7. Calls Canvas.Render() and closes the input frame.
  8. Cleans up stale element storage and style entries.
  9. Records MillisecondsSpent.

​
Core Properties

​
Width
float
Viewport width in logical units, derived from the canvas or the last value passed to SetResolution.
​
Height
float
Viewport height in logical units.
​
ScreenRect
Rect
Convenience rectangle Rect(0, 0, Width, Height) covering the full viewport.
​
DisplayFramebufferScale
Float2
Physical-pixels-per-logical-pixel ratio for the main viewport. Default is (1, 1). Set to (2, 2) on Retina/HiDPI displays so Paper rasterizes fonts and scales vertex output at the correct density. Must be set before BeginFrame.
​
DpiScale
float
Shorthand for DisplayFramebufferScale.X.
​
MainScale
float
Accumulated multiplier applied by all previous calls to ScaleAllSizes. Starts at 1.0.
​
RootElement
ElementHandle
Handle to the invisible root element that owns the entire element hierarchy. Recreated each BeginFrame.
​
Canvas
Canvas
The underlying Prowl.Quill.Canvas used for all draw calls. Available for advanced direct rendering within Draw callbacks.
​
Renderer
ICanvasRenderer
The renderer supplied to the constructor.
​
MillisecondsSpent
float
Wall-clock milliseconds consumed by the last EndFrame call. Useful for performance profiling.
​
CountOfAllElements
uint
Number of distinct elements created during the last frame (after duplicates are detected and before any are removed).
​
CurrentParent
ElementHandle
The element at the top of the internal element stack — i.e., the element whose scope is currently open. All new elements created via Box, Row, Column, etc. are added as children of CurrentParent.

​
Resolution

​
SetResolution

public void SetResolution(float width, float height)
Updates the stored logical viewport size. The change takes effect at the next BeginFrame, which passes the new dimensions to the canvas and uses them when constructing the root element.
​
width
float
required
New logical viewport width.
​
height
float
required
New logical viewport height.

​
ScaleAllSizes

public void ScaleAllSizes(float scaleFactor)
Multiplies every registered default dimensional value (padding, border width, spacing, font sizes, etc.) by scaleFactor. Call once at startup — typically with the monitor DPI ratio — to adapt default style values to HiDPI displays.
​
scaleFactor
float
required
Must be greater than 0. Values less than 1 shrink defaults; values greater than 1 grow them.
Calling ScaleAllSizes multiple times compounds the effect because MainScale is accumulated. If you need to reset, create a new Paper instance.

​
Font Utilities

​
AddFallbackFont

public void AddFallbackFont(FontFile font)
Registers a fallback FontFile with the canvas. When a glyph is missing from the primary font, Paper tries each fallback in registration order.
​
font
FontFile
required
A loaded font file to use as a fallback.

​
EnumerateSystemFonts

public IEnumerable<FontFile> EnumerateSystemFonts()
​
return
IEnumerable<FontFile>
Lazy enumeration of all font files discovered on the host system by the underlying canvas.

​
MeasureText (overload 1)

public Float2 MeasureText(string text, float pixelSize, FontFile font, float letterSpacing = 0.0f)
Measures the rendered bounding box of text without creating a full TextLayout.
​
text
string
required
The string to measure.
​
pixelSize
float
required
Font size in pixels.
​
font
FontFile
required
The font to use for measurement.
​
letterSpacing
float
default:"0.0"
Extra spacing between characters in pixels.
​
return
Float2
Width and height of the measured text in logical pixels.

​
MeasureText (overload 2)

public Float2 MeasureText(string text, TextLayoutSettings settings)
​
text
string
required
The string to measure.
​
settings
TextLayoutSettings
required
Full layout settings including font, size, wrapping, and alignment.
​
return
Float2
Width and height of the measured text.

​
CreateLayout

public TextLayout CreateLayout(string text, TextLayoutSettings settings)
Produces a fully shaped TextLayout object suitable for repeated rendering without re-shaping on every frame.
​
text
string
required
The string to lay out.
​
settings
TextLayoutSettings
required
Layout settings.
​
return
TextLayout
A pre-shaped text layout that can be passed to canvas draw calls.

​
Frame Events

Two Action delegates fire at specific points inside EndFrame, giving you hooks to inject logic at layout boundaries without subclassing Paper.
​
OnEndOfFramePreLayout
Action?
Invoked after style updates but before the layout pass runs. Use this to modify element properties or add elements that depend on computed style but not yet computed positions.
​
OnEndOfFramePostLayout
Action?
Invoked immediately after the layout pass completes, before rendering. Computed X, Y, LayoutWidth, and LayoutHeight values on all elements are stable here.

​
Example: Minimal Frame Loop

var paper = new Paper(myRenderer, 1280, 720, FontAtlasSettings.Default);

// Game/application loop
while (running)
{
    // Feed host input first
    paper.SetPointerPosition(mouseX, mouseY);
    paper.SetPointerState(PaperMouseBtn.Left, mouseX, mouseY, leftDown, false);

    paper.BeginFrame(deltaTime);

    // Build UI
    using (paper.Box("root").Width(paper.Stretch()).Height(paper.Stretch()).Enter())
    {
        // ... child elements ...
    }

    paper.EndFrame();
}
Set DisplayFramebufferScale before the first BeginFrame on HiDPI displays, or pass the scale as the dpiScale argument each frame if it can change at runtime (e.g., window dragged between monitors).

Build docs developers (and LLMs) love

Get started for freeTalk to us