natiny.render.viewport_begin

Lua
natiny.render.viewport_begin(x, y, width, height [, fn])

Sets a rectangular viewport on the current window or surface render target. The viewport becomes the local drawing area: its top-left corner is (0, 0), and its dimensions are used by 2D drawing and cameras bound afterwards.

Parameters

Name Type Default Description
x number Left edge in render-target pixels
y number Top edge in render-target pixels
width number Width in pixels
height number Height in pixels
fn function nil Called with no arguments while the viewport is in force; the viewport is ended when it returns

Example

Lua
for i, pane in ipairs(panes) do
    natiny.render.viewport_begin(pane.x, pane.y, pane.w, pane.h, function()
        natiny.camera.bind(pane.camera)
        draw_scene()
    end)
end

Without the callback, end the viewport by hand:

Lua
natiny.render.viewport_begin(0, 0, 320, 180)
draw_scene()
natiny.render.viewport_end()

Notes

  • The rectangle is clamped to the render target. If the clamped width or height is not positive, no viewport is set.
  • With fn, the viewport is ended when fn returns, including when it raises an error - the error is re-raised afterwards. That is the difference worth having: a skipped viewport_end leaves a viewport open, and every viewport_begin for the rest of the frame is then refused.
  • The callback form is the pair written out and nothing more. Viewports still do not nest: a call made while a viewport is active is ignored, and the end that follows fn closes the outer viewport instead.
  • Setting a viewport clears the existing scissor stack. Scissor coordinates used afterwards are relative to the viewport and are clipped to it.
  • natiny.render.cover() covers the viewport. Bind a camera after setting the viewport to use the viewport's aspect ratio.
  • The viewport is cleared automatically when the render target changes or a window is bound for a new frame.