CameraCapture

CameraCapture represents an image rendered by a Camera to be used elsewhere in the game, for example in UI. Each camera capture instance uses a certain amount of the memory based on the resolution size. Creators are free to create whatever combination (mixed resolutions) of camera captures needed up until the budget is fully consumed. Creators may wish to explicitly release existing capture instances when they are no longer needed, so that they can create more elsewhere. A released capture is no longer valid, and should not be used thereafter.

The total budget is 8 megapixels (8,388,608 pixels).

Below lists the total number of captures that can be done per resolution. Creators can mix the resolution size as long as the total budget is not above the limit of 8 megapixels.

2048 maximum captures at VERY_SMALL resolution size.
512 maximum captures at SMALL resolution size.
128 maximum captures at MEDIUM resolution size.
32 maximum captures at LARGE resolution size.
8 maximum captures at VERY_LARGE resolution size.

Properties

Property Name	Return Type	Description	Tags
`resolution`	`CameraCaptureResolution`	The resolution of this capture.	Read-Only
`camera`	`Camera`	The Camera to capture from.	Read-Write

Functions

Function Name	Return Type	Description	Tags
`IsValid()`	`boolean`	Returns `true` if this capture instance has valid resources.	None
`Refresh()`	`None`	Recaptures the render using the current camera.	None
`Release()`	`None`	Releases the texture resources associated with this capture instance. This instance will become invalid and should no longer be used.	None

Examples

Example using:

`Refresh`

This example uses the Camera's Capture() and Refresh() to implement a rear-view mirror that appears when the player is using a vehicle. For the UI image to look correct, it should have equal width and height, as well as Flip Horizontal enabled.

local CAMERA = script:GetCustomProperty("Camera"):WaitForObject()
local UI_ROOT = script:GetCustomProperty("Root"):WaitForObject()
local IMAGE = script:GetCustomProperty("UIImage"):WaitForObject()
local PLAYER = Game.GetLocalPlayer()

local OFFSET_UP = 150
local OFFSET_BACK = -310

local camCapture = nil

function Capture()
    if camCapture and camCapture:IsValid() then
        camCapture:Refresh()
    else
        camCapture = CAMERA:Capture(CameraCaptureResolution.MEDIUM)
        IMAGE:SetCameraCapture(camCapture)
    end
end

function Tick()
    if Object.IsValid(PLAYER.occupiedVehicle) then
        -- Rotate the camera so it's looking back
        local rot = PLAYER.occupiedVehicle:GetWorldRotation()
        local q = Quaternion.New(rot)
        local upVector = q:GetUpVector()
        local forwardVector = q:GetForwardVector()
        rot = Rotation.New(-forwardVector, upVector)
        CAMERA:SetWorldRotation(rot)
        -- Position the camera relative to the vehicle
        local pos = PLAYER.occupiedVehicle:GetWorldPosition()
        pos = pos + upVector * OFFSET_UP + forwardVector * OFFSET_BACK
        CAMERA:SetWorldPosition(pos)
        -- Update the image
        Capture()
        -- Player is in a vehicle, enable visibility of the mirror
        UI_ROOT.visibility = Visibility.INHERIT
    else
        -- Hide the rear-view mirror, as the player is not in a vehicle
        UI_ROOT.visibility = Visibility.FORCE_OFF
    end
end

Example using:

`camera`

`resolution`

`IsValid`

`Refresh`

`Release`

This client script demonstrates how several in-game cameras can be displayed onto the 2D UI, one at a time, perhaps in a game with some kind of surveillance system. When a camera is selected to be displayed call the Capture() function, passing the camera as parameter.

local UI_IMAGE = script:GetCustomProperty("UIImage"):WaitForObject()

local camCapture = nil

local function Capture(selectedCamera)
    if selectedCamera then
        if not camCapture or not camCapture:IsValid() then
            camCapture = selectedCamera:Capture(CameraCaptureResolution.VERY_LARGE)
            UI_IMAGE:SetCameraCapture(camCapture)
        else
            camCapture.camera = selectedCamera
            camCapture:Refresh()
        end
    end
end

local function ReleaseCapture()
    if camCapture and camCapture:IsValid() then
        print("Release from memory a camera capture with resolution: " .. camCapture.resolution)
        camCapture:Release()
        camCapture = nil
    end
end

script.destroyEvent:Connect(ReleaseCapture)

Last update: June 30, 2022