Displays

Warning: I am looking for volunteers to help me with the docs!

Displays are the primary output devices used by DirectGPU. They allow you to render graphics, text, and images within Lua.

Methods

Method
`autoDetectAndCreateDisplay([resolutionMultiplier : number] or [x : number, y : number])` : number
`autoDetectAndCreateDisplays([maxCount : number, resolutionMultiplier : number])` : table
`autoDetectMonitor([nameOrSide : string])` : number, number, number
`autoDetectMonitors([maxCount : number])` : table
`clearAllDisplays()` : ()
`createDisplay(x : number, y : number, z : number, facing : string, width : number, height : number, [relative : boolean])` : number
`createDisplay(x : number, y : number, z : number, facing : string, width : number, height : number, [scale : number, relative : boolean])` : number
`createDisplay("gui", pixelWidth : number, pixelHeight : number, [resolutionMultiplier : number])` : number
`createDisplayAt(x : number, y : number, z : number, [relative : boolean])` : number
`createDisplayAt(x : number, y : number, z : number, facing : string, width : number, height : number, [scale : number, relative : boolean])` : number
`createDisplayWithResolution(x : number, y : number, z : number, facing : string, width : number, height : number, [resolutionMultiplier : number, relative : boolean])` : number
`enableDeltaMode(displayId : DisplayID)` : ()
`getDisplayFrameJpeg(displayId : DisplayID, [quality : number])` : string
`getDisplayInfo(displayId : DisplayID)` : table
`getDisplayPosition(displayId : DisplayID)` : table
`getRotation(displayId : DisplayID)` : table
`listDisplays()` : table
`mirrorDisplay(sourceDisplayId : DisplayID, targetDisplayIds : table)` : table
`moveDisplay(displayId : DisplayID, targetX : number, targetY : number, targetZ : number, [speed : number, ...])` : ()
`removeDisplay()` : boolean
`setBackgroundOpacity(displayId : DisplayID, opacity : number)` : ()
`setDisplayPersistent(displayId : DisplayID, persistent : boolean)` : ()
`setDisplayPosition(displayId : DisplayID, x : number, y : number, z : number)` : ()
`setOpacity(displayId : DisplayID, opacity : number)` : ()
`setRotation(displayId : DisplayID, pitch : number, yaw : number)` : ()
`stopDisplayMovement(displayId : DisplayID)` : ()
`updateDisplay(displayId : DisplayID)` : ()
`get3DStats(displayId : DisplayID)` : table?

Usage

autoDetectAndCreateDisplay

Automatically finds the nearest display and creates it for DirectGPU.

Optionally accepts a resolutionMultiplier to control the display resolution.

Requires: DisplayID or X: number, Y: number (Currently unknown but working on it;)

Returns: number (or nil if no display is found).

Example

local displayId = gpu.autoDetectAndCreateDisplay()

if displayId then
    print("display found with id: " .. displayId)
else
    print("no display detected")
end

With a resolution multiplier:

local displayId = gpu.autoDetectAndCreateDisplay(1)

autoDetectAndCreateDisplays

Automatically finds and creates multiple displays at once.

Requires: [maxCount : number], [resolutionMultiplier : number]

Returns: Table containing the created DisplayIDs.

Example

local displayIds = gpu.autoDetectAndCreateDisplays(2, 1)

for _, displayId in ipairs(displayIds) do
    print("display found with id: " .. displayId)
end

autoDetectMonitor

Detects a monitor and returns its anchor position. Useful if you want to know where a display would be created.

Requires: [nameOrSide : string]

Returns: x, y, z coordinates (or nil if no display is found).

Example

local x, y, z = gpu.autoDetectMonitor("top")

if x then
    print("Monitor found at: " .. x .. ", " .. y .. ", " .. z)
else
    print("no monitor detected")
end

autoDetectMonitors

Detects multiple monitors and returns their anchor positions.

Requires: [maxCount : number]

Returns: Table containing the detected monitor positions.

Example

local monitors = gpu.autoDetectMonitors(4)

for _, monitor in ipairs(monitors) do
    print(monitor.x, monitor.y, monitor.z)
end

clearAllDisplays

As the name says, it will destroy all displays made by the GPU block used.

Example

gpu.clearAllDisplays()

createDisplay

Creates a display manually at a specific position and facing.

When passing "gui" as the x argument, a GUI display is created on the computer used and on the front texture of the computer. In this mode pixelWidth and pixelHeight control the GUI resolution, with an optional resolutionMultiplier.

Manual display creation also supports relative positions from the DirectGPU block. Passing true as the final relative argument creates the display at a block offset relative to the DirectGPU block instead of an absolute world position.

Requires: x : number, y : number, z : number, facing : string, width : number, height : number

Optional: [relative : boolean] or [scale : number, relative : boolean]

Returns: number (or nil if no display is found).

Example

local displayId = gpu.createDisplay(0, 64, 0, "north", 3, 2)
print("Created display: ", displayId) -- this could print nil, please watch out!

Relative position from the DirectGPU block:

local displayId = gpu.createDisplay(1, 0, 0, "north", 2, 1, true)
print("Created display: ", displayId)

Relative position with scale:

local displayId = gpu.createDisplay(1, 0, 0, "north", 2, 1, 1.0, true)
print("Created display: ", displayId)

GUI display on the computer and its front texture:

local displayId = gpu.createDisplay("gui", 640, 360)
print("Created GUI display: ", displayId)

GUI display with resolution multiplier:

local displayId = gpu.createDisplay("gui", 640, 360, 2)
print("Created GUI display: ", displayId)

createDisplayAt

Creates a display manually at a specific position. This is just createDisplay but with more exact placement.

When only x, y, z are given, the display is anchored at that position. When facing, width and height are also given the full display geometry is specified. Relative offsets from the DirectGPU block are supported via the relative argument.

Requires: x : number, y : number, z : number

Optional: facing : string, width : number, height : number, [scale : number, relative : boolean]

Returns: number (or nil if no display is found).

Example

local displayId = gpu.createDisplayAt(0, 64, 0, "north", 3, 2)
print("Created display: ", displayId) -- this could print nil, please watch out!

Anchored at a detected monitor position:

local x, y, z = gpu.autoDetectMonitor("top")
local displayId = gpu.createDisplayAt(x, y, z)
print("Created display: ", displayId)

Relative position from the DirectGPU block:

local displayId = gpu.createDisplayAt(1, 0, 0, "north", 2, 1, 1.0, true)
print("Created display: ", displayId)

createDisplayWithResolution

Creates a display manually at a specific position, facing and resolution modifier. This is just createDisplay but with resolution modification.

Requires: x : number, y : number, z : number, facing : string, width : number, height : number, [resolutionMultiplier : number]

Optional: [relative : boolean]

Returns: number (or nil if no display is found).

Example

local displayId = gpu.createDisplayWithResolution(0, 64, 0, "north", 3, 2, 1)
print("Created display: ", displayId) -- this could print nil, please watch out!

Relative position from the DirectGPU block:

local displayId = gpu.createDisplayWithResolution(1, 0, 0, "north", 2, 1, 1, true)
print("Created display: ", displayId)

enableDeltaMode

Enables delta mode for a display.

Delta mode only sends changed regions of the framebuffer to the display, reducing network traffic for partially updated screens.

Requires: DisplayID

Example

gpu.enableDeltaMode(displayId)

getDisplayFrameJpeg

Gets the current framebuffer of a display encoded as a JPEG string.

Optionally accepts a quality value to control the JPEG compression.

Requires: DisplayID, [quality : number]

Returns: Base64 encoded JPEG string.

Example

local frame = gpu.getDisplayFrameJpeg(displayId, 80)
print(frame)

getDisplayInfo

Returns information about a display.

Requires: DisplayID

Returns:

{
  id
  x,
  y,
  z
  facing
  width,
  height
  pixelWidth,
  pixelHeight
  resolutionMultiplier
}

Example

local data = gpu.getDisplayInfo(displayId)
if data then
    print(data.id, data.facing, data.width)
end

getDisplayPosition

Gets the current position of a display.

Requires: DisplayID

Returns:

{
  x,
  y,
  z
}

Example

local pos = gpu.getDisplayPosition(displayId)
if pos then
    print(pos.x, pos.y, pos.z)
end

getRotation

Gets the current rotation of a display.

Requires: DisplayID

Returns:

{
  pitch,
  yaw
}

Example

local rot = gpu.getRotation(displayId)
if rot then
    print(rot.pitch, rot.yaw)
end

listDisplays

Lists all displays created by the GPU as table.

Returns: Table containing DisplayIDs.

Example

local data = gpu.listDisplays()
if data then
    print(data)
end

mirrorDisplay

Mirrors the contents of one display onto one or more other displays.

Requires: sourceDisplayId : DisplayID, targetDisplayIds : table

Returns: table

Example

local result = gpu.mirrorDisplay(sourceDisplayId, { displayA, displayB })
print(result)

moveDisplay

Smoothly moves a display to a target position.

Optionally accepts a speed value and additional movement arguments to control the animation.

Requires: DisplayID, targetX : number, targetY : number, targetZ : number

Optional: [speed : number, ...]

Example

gpu.moveDisplay(displayId, 10, 64, 0, 2)

removeDisplay

Deletes a display.

Requires: DisplayID.

Returns: boolean

Example

local ok = gpu.removeDisplay(displayId)
if ok then
    print("The display was removed")
end

setBackgroundOpacity

Sets the opacity used for the display background only.

This only affects the display background, not anything drawn on top of it.

Requires: DisplayID, opacity : number

Example

gpu.setBackgroundOpacity(displayId, 0)

setDisplayPersistent

Marks whether the display should persist. (i dont know what this does but sure!)

Requires: DisplayID, boolean.

Example

gpu.setDisplayPersistent(displayId, true)

setDisplayPosition

Teleports a display to a specific world position.

Requires: DisplayID, x : number, y : number, z : number

Example

gpu.setDisplayPosition(displayId, 5, 64, 0)

setOpacity

Sets the opacity used for anything drawn to the display.

This changes anything drawn to the display, including text, shapes, and images.

Requires: DisplayID, opacity : number

Example

gpu.setOpacity(displayId, 100)

setRotation

Sets the rotation of a display.

Requires: DisplayID, pitch : number, yaw : number

Example

gpu.setRotation(displayId, 10, 45)

stopDisplayMovement

Stops any in-progress movement animation for a display.

Requires: DisplayID

Example

gpu.stopDisplayMovement(displayId)

updateDisplay

Pushes the current framebuffer to the display. Call this after drawing.

Requires: DisplayID.

Example

gpu.updateDisplay(displayId)

Opacity

setOpacity(displayId, opacity) changes anything drawn to the display.

setBackgroundOpacity(displayId, opacity) only changes the display background.

gpu.setOpacity(displayId, 100)
gpu.setBackgroundOpacity(displayId, 0)

get3DStats

Returns statistics about the display’s 3D/rendering state.

Requires: DisplayID.

Example

local s = gpu.get3DStats(id)

for k, v in pairs(s) do
    print(k, v)
end