Screen API

This is main library for efficient usage of GPU resources and rendering data on screen as fast as possible. All MineOS software and internal interface libraries are based on this library.

It's main concept is very simple: there are 6 tables stored in the RAM and containing information about pixels on the screen. The first 3 tables stores what is displayed at the moment, and the other 3 tables - what user is drawing to screen buffer in this moment. After performing all the drawing operations, user calls the screen.drawChanges() method: library will automatically detect changed pixels, group them into an temporary buffer by color values to reduce GPU calls, and finally will display result on screen.

Compared with standard linear rendering, the rendering with this library time is reduced by hundreds and thousands of times. The picture below shows this:

The price of such speed is an increased consumption of RAM. To minimize it, library uses the one-dimensional structure of the pixel data tables instead of the three-dimensional one. To obtain pixel data, special methods are used that convert screen coordinates to screen buffer indices and vice versa, more about this is written below in Auxiliary methods section.

In addition, this library doesn't access any component table directly, replacing them with constants aliases and avoiding calculation of table hashes: for example, instead of instead of gpu.setBackground(...) library uses internal GPUSetBackground(...) function. With a competent implementation, this extremely increases performance without overloading Lua GC.

Contents
Main methods
screen.getResolution
screen.setResolution
screen.bindScreen
screen.bindGPU
Rendering methods
screen.drawChanges
screen.setDrawLimit
screen.getDrawLimit
screen.copy
screen.paste
screen.set
screen.get
screen.drawRectangle
screen.clear
screen.drawText
screen.drawImage
screen.drawLine
screen.drawEllipse
Semi-pixel rendering methods
screen.semiPixelSet
screen.drawSemiPixelSquare
screen.drawSemiPixelLine
screen.drawSemiPixelEllipse
screen.drawSemiPixelCurve
Auxiliary methods
screen.flush
screen.getIndexByCoordinates
screen.getCoordinatesByIndex
screen.rawSet
screen.rawGet
screen.getCurrentFrameTables
screen.getNewFrameTables

Main methods

screen.getResolution(): int width, int height

Get screen buffer resolution. There's also screen.getWidth() and screen.getHeight() methods for your comfort.

screen.setResolution(int width, int height)

Set screen buffer and GPU resolution. Content of buffer will be cleared with black pixels and whitespace symbol.

screen.setGPUProxy(table proxy)

Set the GPU component proxy is used by library to given one. Content of buffer will be cleared with black pixels and whitespace symbol.

screen.bind(string address)

Bind the GPU used by library to given screen component address. Content of buffer will be cleared with black pixels and whitespace symbol.

screen.getGPUProxy(): table GPUProxy

Get a pointer to currently bound GPU component proxy.

Rendering methods

screen.drawChanges([force])

Type	Parameter	Description
[boolean	force]	Force content drawing

Draw contents of screen buffer on screen. If optional argument force is specified, then the contents of screen buffer will be drawn completely and regardless of the changed pixels.

screen.setDrawLimit(x1, y1, x2, y2)

Type	Parameter	Description
int	x1	First point coordinate of draw limit by x-axis
int	y1	First point coordinate of draw limit by y-axis
int	x2	Second point coordinate of draw limit by x-axis
int	y2	Second point coordinate of draw limit by y-axis

Set buffer draw limit to the specified values. In this case, any operations that go beyond the limits will be ignored. By default, the buffer always has a drawing limit in the ranges x ∈ [1; screen.width] and y ∈ [1; screen.height]

screen.getDrawLimit(): int x1, int y1, int x2, int y2

Get currently set draw limit

screen.copy(x, y, width, height): table pixelData

Type	Parameter	Description
int	x	Copied area coordinate by x-axis
int	y	Copied area coordinate by y-axis
int	width	Copied area width
int	height	Copied area height

Copy content of specified area from screen buffer and return it as a table. Later it can be used with screen.paste(...).

screen.paste(x, y, pixelData)

Type	Parameter	Description
int	x	Paste coordinate by x-axis
int	y	Paste coordinate by y-axis
table	pixelData	Table with copied screen buffer data

Paste the copied contents of screen buffer to the specified coordinates.

screen.set(x, y, background, foreground, symbol)

Type	Parameter	Description
int	x	Screen coordinate by x-axis
int	y	Screen coordinate by x-axis
int	background	Background color
int	foreground	Text color
string	symbol	Symbol

Set value of specified pixel on screen.

screen.get(x, y): int background, int foreground, string symbol

Type	Parameter	Description
int	x	Screen coordinate by x-axis
int	y	Screen coordinate by x-axis

Get value of specified pixel on screen.

screen.drawRectangle(x, y, width, height, background, foreground, symbol, transparency)

Type	Parameter	Description
int	x	Rectangle coordinate by x-axis
int	y	Rectangle coordinate by x-axis
int	width	Rectangle width
int	height	Rectangle height
int	background	Rectangle background color
int	foreground	Rectangle text color
string	symbol	The symbol that will fill the rectangle
[float [0.0; 1.0]	transparency]	Optional background transparency

Fill the rectangular area with the specified pixel data. If optional transparency parameter is specified, the rectangle will "cover" existing pixel data, like a glass.

screen.clear([color, transparency])

Type	Parameter	Description
[int	background]	Optional background color
[float [0.0; 1.0]	transparency]	Optional background transparency

It works like screen.square(...), but it applies immediately to all the pixels in the screen. If arguments are not passed, then the buffer is filled with the standard black color and the whitespace symbol.

screen.drawText(x, y, color, text, transparency)

Type	Parameter	Description
int	x	Text coordinate by x-axis
int	y	Text coordinate by y-axis
int	foreground	Text color
string	text	Text
[float [0.0; 1.0]	transparency]	Optional text transparency

Draw the text of the specified color. The background color under text will remain the same. It is also possible to set the transparency of the text.

screen.drawImage(x, y, picture)

Type	Parameter	Description
int	x	Image coordinate by x-axis
int	y	Image coordinate by y-axis
table	picture	Loaded image

Draw image that was loaded earlier via image.load(...) method. The alpha channel of image is also supported.

screen.drawLine(x1, y1, x2, y2, background, foreground, symbol)

Type	Parameter	Description
int	x1	First point coordinate by x-axis
int	y1	First point coordinate by y-axis
int	x2	Second point coordinate by x-axis
int	y2	Second point coordinate by y-axis
int	background	Line background color
int	foreground	Line background color
string	symbol	Line symbol

Draw a line with specified pixel data from first point to second.

screen.drawEllipse(centerX, centerY, radiusX, radiusY, background, foreground, symbol)

Type	Parameter	Description
int	centerX	Ellipse middle point by x-axis
int	centerY	Ellipse middle point by x-axis
int	radiusX	Ellipse radius by x-axis
int	radiusY	Ellipse radius by x-axis
int	background	Ellipse background color
int	foreground	Ellipse background color
string	symbol	Ellipse symbol

Draw ellipse with specified pixel data.

Semi-pixel rendering methods

Allsemi-pixel methods allow to avoid the effect of doubling pixel height of the console pseudographics using special symbols like "▄". In this case, the transmitted coordinates along the Y axis must belong to the interval [0; screen.height * 2].

screen.semiPixelSet(x, y, color)

Type	Parameter	Description
int	x1	Coordinate by x-axis
int	y1	Coordinate by y-axis
int	color	Pixel color

Set semi-pixel value in specified coordinates.

screen.drawSemiPixelRectangle(x, y, width, height, color)

Type	Parameter	Description
int	x	Rectangle coordinate by x-axis
int	y	Rectangle coordinate by y-axis
int	width	Rectangle width
int	height	Rectangle height
int	color	Rectangle color

Draw semi-pixel rectangle.

screen.drawSemiPixelLine(x1, y1, x2, y2, color)

Type	Parameter	Description
int	x1	First point coordinate by x-axis
int	y1	First point coordinate by y-axis
int	x2	Second point coordinate by x-axis
int	y2	Second point coordinate by y-axis
int	color	Line color

Rasterize a semi-pixel line witch specified color.

screen.drawSemiPixelEllipse(centerX, centerY, radiusX, radiusY, color)

Type	Parameter	Description
int	centerX	Ellipse middle point by x-axis
int	centerY	Ellipse middle point by x-axis
int	radiusX	Ellipse radius by x-axis
int	radiusY	Ellipse radius by x-axis
int	color	Ellipse color

Draw semi-pixel ellipse with specified color.

screen.drawSemiPixelCurve(points, color, accuracy)

Type	Parameter	Description
table	points	Table with structure {{x = 32, y = 2}, {x = 2, y = 2}, {x = 2, y = 98}} that contains a set of points for drawing curve
int	color	Curve color
float	accuracy	Curve accuracy. Less = more accurate

Draw the Bezier Curve with specified color

Auxiliary methods

The following methods are used by the library itself or by applications that require maximum performance and calculate the pixel data of the buffer manually. In most cases, they do not come in handy, but they are listed just in case.

screen.flush([width, height])

Type	Parameter	Description
int	width	New screen buffer width
int	height	New screen buffer width

Set screen buffer resolution to the specified one and fill it with black pixels and whitespace stringacter. Unlike screen.setResolution() it does not change the current resolution of the GPU. If optional arguments are not specified, then the buffer size becomes equivalent to the current GPU resolution.

screen.*getIndex( x, y): int index

Type	Parameter	Description
int	x	Screen coordinate by x-axis
int	y	Screen coordinate by y-axis

Convert screen coordinates to the screen buffer index. For example, a 2x1 pixel has a buffer index equals 4, and a pixel of 3x1 has a buffer index equals 7.

screen.getCoordinates(index): int x, int y

Type	Parameter	Description
int	index	Screen buffer index

Convert screen buffer index to it's screen coordinates.

screen.rawSet(index, background, foreground, symbol)

Type	Parameter	Description
int	index	Screen buffer index
int	background	Background color
int	foreground	Text color
string	symbol	Symbol

Set specified data values to pixel with specified index.

screen.rawGet(index): int background, int foreground, string symbol

Type	Parameter	Description
int	index	Screen buffer index

Get data values of pixel with specified index.

screen.getCurrentFrameTables(): table currentFrameBackgrounds, table currentFrameForegrounds, table currentFrameSymbols

Get current screen buffer frames (that is displayed on screen) that contains pixel data. This method is used in rare cases where maximum performance and manual buffer changing pixel-by-pixel is required.

screen.getNewFrameTables(): table newFrameBackgrounds, table newFrameForegrounds, table newFrameSymbols

Works like screen.getCurrentFrameTables(), but returns frames that user is changing in realtime (before calling screen.drawChanges())

Practical example

-- Import required libraries
local buffer = require("doubleBuffering")
local image = require("image")

--------------------------------------------------------------------------------

-- Load image from file and draw it to screen buffer
screen.drawImage(1, 1, image.load("/MineOS/Pictures/Raspberry.pic"))
-- Fill buffer with black color and transparency set to 0.6 to make image "darker"
screen.clear(0x0, 0.6)

-- Draw 10 rectangles filled with random color
local x, y, xStep, yStep = 2, 2, 4, 2
for i = 1, 10 do
	screen.drawRectangle(x, y, 6, 3, math.random(0x0, 0xFFFFFF), 0x0, " ")
	x, y = x + xStep, y + yStep
end

-- Draw yellow semi-pixel ellipse
screen.drawSemiPixelEllipse(22, 22, 10, 10, 0xFFDB40)
-- Draw yellow semi-pixel line
screen.drawSemiPixelLine(2, 36, 35, 3, 0xFFFFFF)
-- Draw green bezier curve with accuracy set to 0.01
screen.drawSemiPixelCurve(
	{
		{ x = 2, y = 63},
		{ x = 63, y = 63},
		{ x = 63, y = 2}
	},
	0x44FF44,
	0.01
)

-- Draw changed pixels on screen
screen.drawChanges()

Result: