Architecture

This page records the current maintenance boundaries for MGFX. Public API details live in API Overview and the API Reference.

What MGFX Owns

MGFX owns rendering:

• shader-backed immediate shapes
• fallback drawing paths
• image masks
• text routing and optional composer text
• frame scopes and clipping
• paint records for gradients and patterns
• prepared scalar/fill/effect draw layers below the public API boundary
• visual transforms
• runtime capability queries

MGFX does not own:

• layout
• input
• focus
• component lifecycle
• animation state
• transitions
• hit testing

Callers compute the current visual state and submit draw calls every frame.

Module Boundaries

These are internal maintenance boundaries, not user-facing entry points. Application code should call the Plain GLua table returned by mgfx/init.lua or the Lux mgfx.api.* facade; it should not decide whether a draw call belongs to roundrect, primitives, widgets, paint, or style.

Area	Responsibility
roundrect	Rounded boxes, circles, capsules, shared glow/shadow style normalization.
primitives	Lines, convex polygons, chamfer boxes, regular polygons, diamonds, carets.
widgets	Progress bars, segment bars, rings, arcs, sectors, images, icons.
style	Fill records, gradients, masks, pattern records, color helpers.
materials	Shaderpack mount, render targets, material creation, shader status.
text	Native text route, shader text composer, measuring, prewarming.
api	Public facade used by Lux and the precompiled runtime.

Hot Draw Pipeline

Public API calls are allowed to accept style tables. Internal renderer code should not keep forwarding those tables once a call has crossed the public API boundary.

The intended shape is:

MGFX.RoundedBoxEx(..., style)
  -> resolve public aliases and defaults once
  -> pass scalar radius/fill/stroke/effect parameters
  -> execute shader/fallback draw path

The renderer should avoid hidden chains like:

widget helper -> temporary style table -> shape helper -> style normalization -> draw

That chain is both harder to read and measurably slower in GMod because it adds table reads, temporary records, cache checks, and duplicated effect normalization before the actual draw call.

Transforms

Transforms are draw-phase visual transforms. They do not affect layout or hit testing.

Do not add primitive-specific projected APIs such as ProjectedRoundedBoxEx or ProjectedRing. Use style.transform, PushTransform, or PointerTilt.

Masks And Clip

Image style masks are per-primitive shader coverage. Reusable MGFX.Mask objects instead define a coverage program consumed by the callback-only MGFX.Clip framebuffer transaction. Neither path uses stencil.

Analytical Circle/Capsule/Rounded/Chamfer presets run directly in the composite shader. Custom painters rasterize MGFX coverage commands into a lazily allocated full-frame RT, cache by content revision, destination/device extent, and fractional pixel phase, then composite before/after framebuffer snapshots. Integer translation does not invalidate the raster. The current backend rejects transformed Clip mapping and caps nesting at four to bound permanent RT allocation.

Every MGFX-owned render-target, camera, model-matrix, scissor, and blend override must be paired in a protected cleanup scope. GMod exposes no getter for existing blend/alpha-write override descriptors, so caller-owned override scopes are outside the Clip contract.

Public API Discipline

The project is still stabilizing, so incompatible public API improvements are allowed when they make the renderer clearer. However, every public API change must update:

• API overview
• grouped API reference
• examples or demos that rely on the old shape
• plain GLua and Lux usage if both are affected

Runtime Packages

Both implementations separate the renderer core from optional integration layers:

Layer	Plain GLua	Lux
Core library	include("mgfx/init.lua")	@lux/mgfx
Global compatibility	mgfx/global.lua	@lux/mgfx/global
Commands and diagnostics	mgfx/devtools.lua	@lux/mgfx/devtools
Examples	mgfx/examples.lua	explicit demo package imports

Importing or including the core must not install public globals, console commands, hooks, diagnostic cvars, or examples. Both core routes expose the same public rendering behavior; adapters are installed only by integrations that need them.