Guides

Examples

Modules

Objects

Callbacks

Texture:newReadback

Edit

Creates and returns a new Readback that will download the pixels in the Texture from VRAM. Once the readback is complete, Readback:getImage returns an Image with a CPU copy of the data.

readback = Texture:newReadback(x, y, layer, mipmap, width, height)

Arguments

NameTypeDefaultDescription
xnumber0 The x offset of the region to download.
ynumber0 The y offset of the region to download.
layernumber1 The index of the layer to download.
mipmapnumber1 The index of the mipmap level to download.
widthnumbernil The width of the pixel rectangle to download. If nil, the "rest" of the width will be used, based on the texture width and x offset.
heightnumbernil The height of the pixel rectangle to download. If nil, the "rest" of the height will be used, based on the texture height and y offset.

Returns

NameTypeDescription
readbackReadback A new Readback object.

Notes

The texture must have been created with the transfer usage.

Multisampled textures can not be read back.

It is not currently possible to read back a texture view.

Example

Take a screenshot when pressing a key. This uses an intermediate texture and render pass, to work around the fact that the window/headset textures don't support transfers.

local screenshot = false
local readback
local texture
local pass

function lovr.keypressed(key)
  if key == 'p' then screenshot = true end
end

function lovr.load()
  local width, height = lovr.headset.getDisplayDimensions()

  texture = lovr.graphics.newTexture(width, height, {
    usage = { 'render', 'transfer', 'sample' }
  })

  pass = lovr.graphics.newPass(texture)
end

function lovr.update()
  pass:reset()
  for i = 1, lovr.headset.getViewCount() do
    pass:setViewPose(i, lovr.headset.getViewPose(i))
    pass:setProjection(i, lovr.headset.getViewAngles(i))
  end
  pass:text('hellooo', 0, 1.7, -1, .1)
  lovr.graphics.submit(pass)

  if screenshot and not readback then
    readback = texture:newReadback()
    screenshot = false
  end

  if readback and readback:isComplete() then
    local filename = 'screenshot.png'
    lovr.filesystem.write(filename, readback:getImage():encode())
    print('saved screenshot to ' .. filename)
    readback = nil
  end
end

function lovr.draw(p)
  p:fill(texture)
end

See also