组件：GPU ============== 此组件由[[item:graphics_card:zh|显卡]]提供。对简单程序而言只需使用[[api:term:zh|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`。 回调函数： - [[component:gpu:zh#显存缓冲区|显存缓冲区]] 此处的组件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` 设定要使用的色深。最大值可以为硬件支持的最大色深。若给定值超出范围或无效则会抛出错误。返回值为旧的色深，取值可为下列字符串之一：`OneBit`、`FourBit`或`EightBit`。 \\ - `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` 将屏幕缓冲区的一部分复制到另一个位置。复制来源为矩形，由`x`、`y`、`width`与`height`参数决定。目标位置由`x + tx`、`y + ty`、`width`与`height`决定（即`tx`和`ty`为相对坐标）。若成功返回`true`，若失败返回`false`。 \\ - `fill(x: number, y: number, width: number, height: number, char: string): boolean` 用指定字符填充屏幕缓冲区中的一个矩形区域。目标矩形区域由`x`与`y`坐标以及矩形的`width`（宽度）和`height`（高度）决定。填充字符参数`char`必须是长度为1的字符串，即单个字符。若成功返回`true`，若失败返回`false`。 请注意用空格（` `）填充屏幕通常耗能更少，因为此操作被视为"清除"操作（见配置文件）。 使用例： ```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.setDepth`和`gpu.getDepth`）可以为1、4或8位，前景与背景色的色深可以不同。这三种色深分别可以提供2、16和256色。 颜色值（传递给`gpu.setBackground`和`gpu.setForeground`的`number`型参数）会被解释为每通道8位的RGB颜色值（24位色）或某个调色板索引号。 RGB颜色 ----------- 调用`setBackground`与`setForeground`时需要用到前景色与背景色，它们由`value`（数字型）和`is_palette`（布尔型）这一对变量定义（后者为可选）。 若`is_palette`为`false`（或`nil`），`value`将被理解为24位RGB颜色值（0xRRGGBB），无论色深如何。但是给定颜色将会被取近似值为当前色深中与其最接近的颜色。单色的情况下，只有0会近似为0，任何非零值都会近似为1（代表使用设定好的那种颜色）。在4位色的情况下，会近似取调色盘中最接近的颜色。在8位色的情况下，会近似取可用的256种颜色种最接近的颜色。256种可用颜色如下表所示： {{:api:oc-256-color.png?nolink&768|}} 图片由[Eunomiac](https://oc.cil.li/index.php?/topic/442-colors-what-determines-colors-i-code-vs-colors-i-get/)制作 调色板颜色 ----------- 当`is_palette`为`true`时，`value`将被理解为调色板中的索引号，范围为[0,15]。请注意，如果你从高色深切换到单色，系统会使用调色板中的颜色值来判定某种颜色转为单色后是0值还是非0值。在1位色深的情况下给定某种调色板颜色（即给定一个索引号和`true`）会出现错误。 改变色深 ----------- 请注意，哪怕是在切换色深后，原始的颜色值对（代表数据的`number`值与代表是否为调色板颜色的`bool`型值）也会保留。实际在屏幕上渲染的颜色会被更新以符合新色深的限制，但是原始的24位RGB颜色值（或是调色板索引号）也不会丢失。例如，在处于1位色深模式下调用`gpu.getBackground`函数也会返回在先前的色深模式下指定的24位RGB颜色值。 显存缓冲区 ============== 显卡的内部有显存，你可以将他们以页的形式进行分配。你可以自定义页大小（宽与高都需要大于0）。每次分配都会从显卡的显存中扣除`宽度*高度`的大小。高级别GPU的显存比低级别的多。页缓冲区的工作方式类似于隐藏不渲染的[[component:screen:zh|屏幕]]，有其自己的宽度、高度和色深。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` 分配一个大小为`width`x`height`的新页（默认大小为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`。 目录 ---- {{page>component:contents:zh&noheader&noeditbutton&nouser&nofooter}}