Table of Contents

Component: GPU

This is the component provided by graphics cards. For simple programs the term API is 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.

Component name: gpu.
Callbacks:

Example use:

snippet.lua
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

GPU Color Depth

Color Depth (see gpu.setDepth and 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.setBackground and gpu.setForeground) is interpreted either as a 8 bits per channel rgb value (24 bit color) or a palette index.

RGB Color

The background and foreground colors, as set by calling setBackground and setForeground, are defined by a value (number) and is_palette (boolean) pair (the boolean being optional).

When is_palette is false (or nil), 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

Palette Color

When is_palette is true, 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.

Changing 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.

Video Ram Buffers

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.

Budget and Energy Costs

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.