This is the component provided by graphics cards. For simple programs the term API will usually all you need. For more complex operations, or to get a bit more performance, you may wish to interact with the GPU directly, though.
As of OC 1.3 screens of tier 2 and 3 have a 16 color palette. The palette is used to determine the exact colors used when displaying an RGB color.
For tier two this palette contains all colors the screen can possibly display, and is initialized to the standard Minecraft colors. As a side-effect you can specify the colors using
gpu.setBackground(colors.red, true), for example. Keep in mind this only works on tier two screens.
Tier three also has an editable 16 color palette, and also a 240 color fixed palette. The editable palette is initialized to grayscale values. The remaining 240 colors are stored as truncated RGB values as was the case in older versions of OpenComputers.
bind(address: string[, reset: boolean=true]): boolean[, string]
falseand an error message on failure. Resets the screen's settings if reset is 'true'. A GPU can only be bound to one screen at a time. All operations on it will work on the bound screen. If you wish to control multiple screens at once, you'll need to put more than one graphics card into your computer.
getBackground(): number, boolean
0xRRGGBB, or a palette index. The second returned value indicates which of the two it is (
truefor palette color,
falsefor RGB value).
setBackground(color: number[, isPaletteIndex: boolean]): number[, index]
nil. Note that the color is expected to be specified in hexadecimal RGB format, i.e.
0xRRGGBB. This is to allow uniform color operations regardless of the color depth supported by the screen and GPU.
getForeground(): number, boolean
getBackground, but for the foreground color.
setForeground(color: number[, isPaletteIndex: boolean]): number[, index]
setBackground, but for the foreground color.
getPaletteColor(index: number): number
setPaletteColor(index: number, value: number): number
setDepth(bit: number): string
maxResolution(): number, number
getResolution(): number, number
setResolution(width: number, height: number): boolean
trueif the resolution was changed (may return
falseif an attempt was made to set it to the same value it was set before),
getViewport(): number, number
setViewport(width: number, height: number): boolean
trueif it was changed (may return
falseif an attempt was made to set it to the same value it was set before),
falseotherwise. This makes it look like screen resolution is lower, but the actual resolution stays the same. Characters outside top-left corner of specified size are just hidden, and are intended for rendering or storing things off-screen and copying them to the visible area when needed. Changing resolution will change viewport to whole screen.
getSize(): number, number
get(x: number, y: number): string, number, number, number or nil, number or nil
set(x: number, y: number, value: string[, vertical:boolean]): boolean
trueif the string was set to the buffer,
copy(x: number, y: number, width: number, height: number, tx: number, ty: number): boolean
heightparameters. The target rectangle is defined by
x + tx,
y + ty,
fill(x: number, y: number, width: number, height: number, char: string): boolean
ycoordinates and the rectangle's
height. The fill character
charmust be a string of length one, i.e. a single character. Returns
) is usually less expensive, i.e. consumes less energy, because it is considered a “clear” operation (see config).
local component = require("component") local gpu = component.gpu -- get primary gpu component local w, h = gpu.getResolution() gpu.fill(1, 1, w, h, " ") -- clears the screen gpu.setForeground(0x000000) gpu.setBackground(0xFFFFFF) gpu.fill(1, 1, w/2, h/2, "X") -- fill top left quarter of screen gpu.copy(1, 1, w/2, h/2, w/2, h/2) -- copy top left quarter of screen to lower right
Color Depth (see
gpu.getDepth) can be 1, 4, or 8 bits separately for foreground and background. These depths provide 2, 16, and 256 colors respectively.
The color value (the
number passed to
gpu.setForeground) is interpreted either as a 8 bits per channel rgb value (24 bit color) or a palette index.
The background and foreground colors, as set by calling
setForeground, are defined by a
value (number) and
is_palette (boolean) pair (the boolean being optional).
is_palette is false (or
value is interpreted as a 24 bit rgb color (0xRRGGBB), regardless of depth. However, the color is approximated to the closest available color in the given depth. In monochrome, zero rounds to zero and all nonzero values round to 1 (and the configured monochrome color is used). In 4 bit color, the closest available color in the palette is selected. In 8 bit color the closest color of the available 256 colors is used. The available 256 colors are described in the following table:
Image by Eunomiac
value is interpreted as palette index [0, 16). If you switch from a higher bit density to monochrome note that the color value from the palette is used to determine zero vs the nonzero monochrome color. It is an error to specify a paletted color (i.e. an index value and
true) in 1 bit depth.
Note that the original color pair (the value
number and palette
bool) are preserved (background and foreground each) even when switching bit depths. The actual rendering on the screen will update to respect the new depth, but the original 24bit rgb value (or palette index) is not lost. For example, calling
gpu.getBackground while in 1 bit mode will return the original 24 bit rgb value specified from any previous color depth.
A GPU card has internal memory that you can allocate into pages. You can specify a custom page size (width and height each must be greater than zero). The total memory of a GPU is reduced by the width*height of an allocation. Each tier of gpu has more total memory than the last. Each page buffer acts like an offscreen Screen with its own width, height, and color. The max color depth of a gpu buffer is based on the gpu tier. Rebooting a machine releases all bufffers.
Each page buffer has its own index; the gpu finds the next available index. Index zero (0) has a special meaning, it is reserved for the screen. Whether a gpu is bound to a screen or not, you can allocate pages, set them active, and read/write to them. Attaching and detaching a screen, even binding to a new screen, does not release the gpu pages. When a computer shuts off or reboots, the pages are released. Each GPU has its own video memory and pages.
Updates to vram (set, copy, fill, etc) are nearly free. They have no energy cost and no additional budget cost. Every direct component invoke (and these gpu methods are direct) has a tiny system minimum budget cost, but the gpu itself in these vram updates adds no additional cost. When bitblt'ing the vram to the screen there is some cost, similar to how updates to the screen normally incur a cost. A dirty (modified) vram back buffer has a one time budget cost that increases with the size of the source buffer. Subsequent bitblts from a clean back buffer to the screen have extremely low costs.
setActiveBuffer(index: number): number
index. 0 is reserved for the screen and can be set even when there is no screen. Returns nil for an invalid index (0 is valid even with no screen)
allocateBuffer([width: number, height: number]): number
freeBuffer([index: number]): boolean
index(default: current buffer index). Returns true if the buffer was removed. When you remove the currently selected buffer, the gpu automatically switches back to index 0 (reserved for a screen)
getBufferSize([index: number]): number, number
index(default: current buffer index). Returns the screen resolution for index 0. Returns nil for invalid indexes
bitblt([dst: number, col: number, row: number, width: number, height: number, src: number, fromCol: number, fromRow: number])
|Components||3D Printer - Abstract Bus - Access Point - Chunkloader - Computer - Crafting - Data Card - Database - Debug - Drone - Drive - EEPROM - Experience - Filesystem - Generator - Geolyzer - GPU - Hologram - Internet - Inventory Controller - Leash - Microcontroller - Modem - Motion Sensor - Navigation - Net Splitter - Piston - Redstone - Robot - Screen - Sign - Tank Controller - Tractor Beam - Transposer - Tunnel - World Sensor|
|Others||Component Access - Signals|
|Cross-Mod Integration||Applied Energistics|