组件:GPU

此组件由显卡提供。对简单程序而言只需使用term(终端) API即可满足需求。而为了实现更复杂的操作或提高运行性能,你可能会需要直接与GPU交互。

OC 1.3中的2级与3级屏幕有一个16色调色板。调色板的作用是决定显示RGB颜色时使用的具体颜色。

对2级屏幕而言,调色板包含的颜色即为屏幕能显示的所有颜色,默认为Minecraft的16种标准颜色。这种特性带来的副作用是你可以使用如这样的写法:gpu.setBackground(colors.red, true)(使用color API而不是16进制颜色,见下文函数的描述)。请注意这种写法仅可用于2级屏幕

3级屏幕也有可编辑的16色调色板,同时还有240色的固定调色板。可编辑调色板默认为灰度值,其余的240色为缩减过的RGB颜色值,与OC模组早期版本的情况相同。

组件名:gpu

回调函数:

  • 显存缓冲区
    此处的组件API列表已经很长了,因此新加入的显存API在此页面下方自己的章节处列出。
    这些函数在1.7.5 Developer builds版本的OC加入,会在下个发行版(OC 1.8)推出。

  • bind(address: string[, reset: boolean=true]): boolean[, string]
    尝试将GPU绑定到指定屏幕。若成功返回true,若失败返回false和一条报错信息。若reset参数为true则重置屏幕的设置。
    一个GPU同一时间只能被绑定到一块屏幕。在其上进行的一切操作都会在所绑定的屏幕上进行。如果你希望同时控制多块屏幕,则需要在电脑中安装多张显卡。

  • getScreen():string
    获取GPU绑定的屏幕的地址。此函数自1.3.2起添加。

  • getBackground(): number, boolean
    获取当前的背景色。背景色会被应用于一切其他操作改动的“像素”上。 请注意返回值可能是16进制的RGB颜色值,即0xRRGGBB,也可能是调色板索引号。第二个返回值代表了第一个返回值是上述哪一种(true代表调色板颜色, false代表RGB颜色值)。

  • setBackground(color: number[, isPaletteIndex: boolean]): number[, index]
    设定应用于此后其他操作修改的“像素”上的背景色。返回值为旧背景色,为其实际值(即未被压缩到当前设定的色彩空间的值)。第一个返回值为先前颜色的RGB颜色值。若颜色来自调色板,则第二个返回值为其在调色板中的索引号,否则为nil
    请注意调用时给定的颜色值需要为16进制RGB颜色值,即0xRRGGBB。这是为了能统一颜色操作,无需考虑屏幕或GPU支持的色深。

  • getForeground(): number, boolean
    类似getBackground,但是为前景色。

  • setForeground(color: number[, isPaletteIndex: boolean]): number[, index]
    类似setBackground,但是为前景色。

  • getPaletteColor(index: number): number
    获取调色盘中指定索引号对应颜色的RGB颜色值。

  • setPaletteColor(index: number, value: number): number
    设定调色盘中指定索引号对应颜色的RGB颜色值。

  • maxDepth(): number
    获取GPU与其绑定屏幕支持的最大色深(二者取较小值)。

  • getDepth(): number
    获取GPU/屏幕当前设定的色深,单位为位(bit)。值可为1、4或8。

  • setDepth(bit: number): string
    设定要使用的色深。最大值可以为硬件支持的最大色深。若给定值超出范围或无效则会抛出错误。返回值为旧的色深,取值可为下列字符串之一:OneBitFourBitEightBit

  • maxResolution(): number, number
    获取GPU与其绑定屏幕支持的最大分辨率(二者取较小值)。

  • getResolution(): number, number
    获取当前设定的分辨率。

  • setResolution(width: number, height: number): boolean
    设定分辨率。最大值可以为硬件支持的最大分辨率。若给定值超出范围或无效则会抛出错误。若分辨率成功修改则返回true(尝试将分辨率设定为与当前分辨率相同也可能会返回false),若失败则返回false

  • getViewport(): number, number
    获取可见区域的分辨率。

  • setViewport(width: number, height: number): boolean
    设定可见区域的分辨率。若修改成功则返回true(尝试将分辨率设定为与当前分辨率相同也可能会返回false),若失败则返回false。此操作会使得屏幕分辨率看上去降低,但实际分辨率仍然不变。超出指定区域左上角的字符只是隐藏不显示,此功能是为了能在屏幕外渲染或显示内容,并在需要时将它们复制到可视区域内。改动分辨率会将可见区域修改为与分辨率相同。

  • getSize(): number, number
    获取显卡绑定到的屏幕的尺寸,大小为格。对单方块屏幕和机器人而言只有一个。
    已废弃,请改用screen.getAspectRatio()

  • get(x: number, y: number): string, number, number, number or nil, number or nil
    获取指定坐标处当前显示的字符。第二个与第二个返回值是前景和背景色,形式为16进制值。若颜色来自调色盘,第四个和第五个返回值将代表颜色的调色板索引号,否则为nil

  • set(x: number, y: number, value: string[, vertical:boolean]): boolean
    向屏幕写一条字符串,从指定坐标开始。字符串将会被直接复制到屏幕缓冲区,仅复制到单行。这意味着就算有换行符给定字符串也不会换行,换行符只会被以特殊字符的形式显示,字符串不会以多行显示。若字符串被成功传输给缓冲区则返回true,若失败则返回false
    第四个参数为可选参数,若为true可以使给定文本竖行显示。

  • copy(x: number, y: number, width: number, height: number, tx: number, ty: number): boolean
    将屏幕缓冲区的一部分复制到另一个位置。复制来源为矩形,由xywidthheight参数决定。目标位置由x + txy + tywidthheight决定(即txty为相对坐标)。若成功返回true,若失败返回false

  • fill(x: number, y: number, width: number, height: number, char: string): boolean
    用指定字符填充屏幕缓冲区中的一个矩形区域。目标矩形区域由xy坐标以及矩形的width(宽度)和height(高度)决定。填充字符参数char必须是长度为1的字符串,即单个字符。若成功返回true,若失败返回false
    请注意用空格( )填充屏幕通常耗能更少,因为此操作被视为“清除”操作(见配置文件)。

使用例:

snippet.lua
local component = require("component")
local gpu = component.gpu --获取首选GPU组件
local w, h = gpu.getResolution()
gpu.fill(1, 1, w, h, " ") --清空屏幕
gpu.setForeground(0x000000)
gpu.setBackground(0xFFFFFF)
gpu.fill(1, 1, w/2, h/2, "X") --填充屏幕的左上四分之一区域
gpu.copy(1, 1, w/2, h/2, w/2, h/2) --将屏幕的左上四分之一复制到右下

GPU色深

色深(参见gpu.setDepthgpu.getDepth)可以为1、4或8位,前景与背景色的色深可以不同。这三种色深分别可以提供2、16和256色。

颜色值(传递给gpu.setBackgroundgpu.setForegroundnumber型参数)会被解释为每通道8位的RGB颜色值(24位色)或某个调色板索引号。

RGB颜色

调用setBackgroundsetForeground时需要用到前景色与背景色,它们由value(数字型)和is_palette(布尔型)这一对变量定义(后者为可选)。

is_palettefalse(或nil),value将被理解为24位RGB颜色值(0xRRGGBB),无论色深如何。但是给定颜色将会被取近似值为当前色深中与其最接近的颜色。单色的情况下,只有0会近似为0,任何非零值都会近似为1(代表使用设定好的那种颜色)。在4位色的情况下,会近似取调色盘中最接近的颜色。在8位色的情况下,会近似取可用的256种颜色种最接近的颜色。256种可用颜色如下表所示:

图片由Eunomiac制作

调色板颜色

is_palettetrue时,value将被理解为调色板中的索引号,范围为[0,15]。请注意,如果你从高色深切换到单色,系统会使用调色板中的颜色值来判定某种颜色转为单色后是0值还是非0值。在1位色深的情况下给定某种调色板颜色(即给定一个索引号和true)会出现错误。

改变色深

请注意,哪怕是在切换色深后,原始的颜色值对(代表数据的number值与代表是否为调色板颜色的bool型值)也会保留。实际在屏幕上渲染的颜色会被更新以符合新色深的限制,但是原始的24位RGB颜色值(或是调色板索引号)也不会丢失。例如,在处于1位色深模式下调用gpu.getBackground函数也会返回在先前的色深模式下指定的24位RGB颜色值。

显存缓冲区

显卡的内部有显存,你可以将他们以页的形式进行分配。你可以自定义页大小(宽与高都需要大于0)。每次分配都会从显卡的显存中扣除宽度*高度的大小。高级别GPU的显存比低级别的多。页缓冲区的工作方式类似于隐藏不渲染的屏幕,有其自己的宽度、高度和色深。GPU缓冲区支持的最大色深由GPU的等级决定。重启电脑将会释放所有的缓冲区。

每个缓冲区页都有序号,GPU会查找下一个可用序号。序号零(0)有特殊用途,它是为屏幕保留的。无论GPU是否绑定到屏幕,你都可以分配页,设定它们是否启用,以及对它们进行读写。连接与断开屏幕,甚至是绑定到新屏幕,都不会释放GPU的页;而当电脑关机或重启时,页会被释放。每个GPU都有其独立的显存和页。

资源配额与能耗

对显存的更新操作(set、copy和fill等)几乎没有消耗。这些操作不会耗能,也不会额外消耗资源配额。每次直接组件调用(GPU方法即为直接调用)都只消耗很少的系统资源配额,但是GPU本身在显存更新操作中不会增加资源消耗。将显存传输到屏幕时会有一定的资源消耗,类似于屏幕更新时产生的资源消耗。传输脏的(修改过的)显存后备缓冲区需要一次性消耗一定的资源,消耗的量随源缓冲区的大小而增加。而后续从干净的后备缓冲区到屏幕的传输只需要消耗极少的资源。

  • getActiveBuffer(): number
    返回当前选中缓冲区的编号。0被保留给屏幕,且就算没有屏幕也有可能会返回0。

  • setActiveBuffer(index: number): number
    将活动缓冲区设定为index。0被保留给屏幕,且就算没有屏幕也可以设定。若编号无效则返回nil(0就算在没有屏幕的情况下也有效)。

  • buffers(): table
    返回包含当前所有页编号的数组(列表中不包含0,此编号保留给屏幕)。

  • allocateBuffer([width: number, height: number]): number
    分配一个大小为widthxheight的新页(默认大小为GPU的最大分辨率)。返回此缓冲区的编号,若剩余显存不足则报错。即使GPU未绑定到屏幕也可以分配缓冲区。编号0永久保留给屏幕,因此所分配缓冲区的编号最小从1开始。

  • freeBuffer([index: number]): boolean
    移除编号为index(默认为当前缓冲区编号)的缓冲区。若成功移除此缓冲区则返回true。如果你移除了当前选中的缓冲区,GPU会自动切换回编号0(为屏幕保留)。

  • freeAllBuffers()
    移除全部缓冲区,释放所有显存。在调用此函数后活动缓冲区编号一定为0。

  • totalMemory(): number
    返回GPU的显存总量。此值不包括屏幕。

  • freeMemory(): number
    返回未分配给缓冲区的空闲显存总量。此值不包括屏幕。

  • getBufferSize([index: number]): number, number
    返回编号为index的缓冲区(默认为当前缓冲区)的大小。若编号为0则返回屏幕的分辨率。若编号无效则返回nil

  • bitblt([dst: number, col: number, row: number, width: number, height: number, src: number, fromCol: number, fromRow: number])
    将一个矩形区域从缓冲区复制到缓冲区,从屏幕复制到缓冲区或从缓冲区复制到屏幕。
    默认值:
    • dst = 0,代表屏幕
    • col, row = 1,1
    • width, height = 目标缓冲区的分辨率
    • src = 当前缓冲区
    • fromCol, fromRow = 1,1
      bitblt(位块传输)在反复进行时应当执行得很快。若缓冲区是脏的,那么与目标对象同步缓冲区的初始成本会更高。如果你需要大量进行更新,导致频繁进行位块传输,那么可以考虑分配数量多而尺寸小的缓冲区。如果你希望使用一个静态缓冲区(很少或不进行更新),那么分配大的缓冲区即可。
      操作成功后会返回true

目录