natiny.surface.bind

Lua
natiny.surface.bind(surf [, slot] [, fn])

Makes the surface a render target. Bind it while a window is bound so drawing has an active frame command buffer. Multiple surfaces can be bound to distinct slots for one pass.

Parameters

Name Type Default Description
surf number Surface handle from natiny.surface.create
slot number 0 Target slot, 0 to natiny.surface.MAX_TARGETS - 1
fn function nil Callback run while the surface is bound

Example

Lua
natiny.window.bind(win, function()
    natiny.surface.bind(rt, function()
        draw_scene()
    end)
end)

Notes

  • Bind a window before binding a surface.
  • Slot 0 opens a target set and determines its size, 2D projection, and depth attachment. Other slots add colour targets to that set. All surfaces in a set must have identical dimensions.
  • natiny.surface.unbind ends the entire target set; individual slots cannot be unbound.
  • Binding slot 0 suspends the current target state. The matching unbind restores it; see The bind stack.
  • A bind flushes the current batch and ends the current render pass.
  • Surface binds may nest up to 64 stored levels. Deeper binds still take effect, but their previous state cannot be restored.
  • Rebinding a surface preserves its color and depth contents. Call natiny.render.clear explicitly when they should be replaced.
  • A surface also preserves its contents across frames. Clear passes that redraw the complete image, including its depth buffer.
  • A new target set starts with no camera. Bind the camera after slot 0 so its projection uses the target's aspect ratio.
  • With fn, Lua unbinds the target set even if the callback raises an error, then propagates the error.