Differences

This shows you the differences between two versions of the page.

--- component:gpu:zh [2023/10/30 09:00]
hfsr created
+++ component:gpu:zh [2023/12/27 02:03] (current)
hfsr [资源配额与能耗]
@@ Line 1: / Line 1: @@
-Component: GPU
+组件：GPU
 ==============
-This is the component provided by [[item:graphics_card|graphics cards]]. For simple programs the [[api:term|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.
+此组件由[[item:graphics_card:zh|显卡]]提供。对简单程序而言只需使用[[api:term:zh|term(终端) API]]即可满足需求。而为了实现更复杂的操作或提高运行性能，你可能会需要直接与GPU交互。
-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.
+OC 1.3中的2级与3级屏幕有一个16色调色板。调色板的作用是决定显示RGB颜色时使用的具体颜色。
-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**.
+对2级屏幕而言，调色板包含的颜色即为屏幕能显示的所有颜色，默认为Minecraft的16种标准颜色。这种特性带来的副作用是你可以使用如这样的写法：`gpu.setBackground(colors.red, true)`（使用color API而不是16进制颜色，见下文函数的描述）。请注意**这种写法仅可用于2级屏幕**。
-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`.
+级屏幕也有可编辑的16色调色板，同时还有240色的固定调色板。可编辑调色板默认为灰度值，其余的240色为缩减过的RGB颜色值，与OC模组早期版本的情况相同。
-Callbacks:
-- [[component:gpu#video_ram_buffers|Video Ram Buffers]]
+组件名：`gpu`。
-  This list of component api is getting long, so the new video ram api is listed below on this page in its own section
-  - New in OC 1.7.5 Developer builds and expected in the next release (OC 1.8)
+回调函数：
+- [[component:gpu:zh#显存缓冲区|显存缓冲区]]
+  此处的组件API列表已经很长了，因此新加入的显存API在此页面下方自己的章节处列出。
+  这些函数在1.7.5 Developer builds版本的OC加入，会在下个发行版（OC 1.8）推出。
+\\
 - `bind(address: string[, reset: boolean=true]): boolean[, string]`
-  Tries to bind the GPU to a screen with the specified address. Returns `true` on success, `false` and an error message on failure. Resets the screen's settings if reset is 'true'.
+  尝试将GPU绑定到指定屏幕。若成功返回`true`，若失败返回`false`和一条报错信息。若`reset`参数为`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.
+  一个GPU同一时间只能被绑定到一块屏幕。在其上进行的一切操作都会在所绑定的屏幕上进行。如果你希望同时控制多块屏幕，则需要在电脑中安装多张显卡。
+\\
 - `getScreen():string`
-  Get the address of the screen the GPU is bound to. Since 1.3.2.
+  获取GPU绑定的屏幕的地址。此函数自1.3.2起添加。
+\\
 - `getBackground(): number, boolean`
-  Gets the current background color. This background color is applied to all "pixels" that get changed by other operations.
+  获取当前的背景色。背景色会被应用于一切其他操作改动的“像素”上。
-  Note that the returned number is either an RGB value in hexadecimal format, i.e. `0xRRGGBB`, or a palette index. The second returned value indicates which of the two it is (`true` for palette color, `false` for RGB value).
+  请注意返回值可能是16进制的RGB颜色值，即`0xRRGGBB`，也可能是调色板索引号。第二个返回值代表了第一个返回值是上述哪一种（`true`代表调色板颜色， `false`代表RGB颜色值）。
+\\
 - `setBackground(color: number[, isPaletteIndex: boolean]): number[, index]`
-  Sets the background color to apply to "pixels" modified by other operations from now on. The returned value is the old background color, as the actual value it was set to (i.e. not compressed to the color space currently set). The first value is the previous color as an RGB value. If the color was from the palette, the second value will be the index in the palette. Otherwise it will be `nil`.
+  设定应用于此后其他操作修改的“像素”上的背景色。返回值为旧背景色，为其实际值（即未被压缩到当前设定的色彩空间的值）。第一个返回值为先前颜色的RGB颜色值。若颜色来自调色板，则第二个返回值为其在调色板中的索引号，否则为`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.
+  请注意调用时给定的颜色值需要为16进制RGB颜色值，即`0xRRGGBB`。这是为了能统一颜色操作，无需考虑屏幕或GPU支持的色深。
+\\
 - `getForeground(): number, boolean`
-  Like `getBackground`, but for the foreground color.
+  类似`getBackground`，但是为前景色。
+\\
 - `setForeground(color: number[, isPaletteIndex: boolean]): number[, index]`
-  Like `setBackground`, but for the foreground color.
+  类似`setBackground`，但是为前景色。
+\\
 - `getPaletteColor(index: number): number`
-  Gets the RGB value of the color in the palette at the specified index.
+  获取调色盘中指定索引号对应颜色的RGB颜色值。
+\\
 - `setPaletteColor(index: number, value: number): number`
-  Sets the RGB value of the color in the palette at the specified index.
+  设定调色盘中指定索引号对应颜色的RGB颜色值。
+\\
 - `maxDepth(): number`
-  Gets the maximum supported color depth supported by the GPU and the screen it is bound to (minimum of the two).
+  获取GPU与其绑定屏幕支持的最大色深（二者取较小值）。
+\\
 - `getDepth(): number`
-  The currently set color depth of the GPU/screen, in bits. Can be 1, 4 or 8.
+  获取GPU/屏幕当前设定的色深，单位为位（bit）。值可为1、4或8。
+\\
 - `setDepth(bit: number): string`
-  Sets the color depth to use. Can be up to the maximum supported color depth. If a larger or invalid value is provided it will throw an error. Returns the old depth as one of the strings `OneBit`, `FourBit`, or `EightBit`.
+  设定要使用的色深。最大值可以为硬件支持的最大色深。若给定值超出范围或无效则会抛出错误。返回值为旧的色深，取值可为下列字符串之一：`OneBit`、`FourBit`或`EightBit`。
+\\
 - `maxResolution(): number, number`
-  Gets the maximum resolution supported by the GPU and the screen it is bound to (minimum of the two).
+  获取GPU与其绑定屏幕支持的最大分辨率（二者取较小值）。
+\\
 - `getResolution(): number, number`
-  Gets the currently set resolution.
+  获取当前设定的分辨率。
+\\
 - `setResolution(width: number, height: number): boolean`
-  Sets the specified resolution. Can be up to the maximum supported resolution. If a larger or invalid resolution is provided it will throw an error. Returns `true` if the resolution was changed (may return `false` if an attempt was made to set it to the same value it was set before), `false` otherwise.
+  设定分辨率。最大值可以为硬件支持的最大分辨率。若给定值超出范围或无效则会抛出错误。若分辨率成功修改则返回`true`（尝试将分辨率设定为与当前分辨率相同也可能会返回`false`），若失败则返回`false`。
+\\
 - `getViewport(): number, number`
-  Get the current viewport resolution.
+  获取可见区域的分辨率。
+\\
 - `setViewport(width: number, height: number): boolean`
-  Set the current viewport resolution. Returns `true` if it was changed (may return `false` if an attempt was made to set it to the same value it was set before), `false` otherwise. 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.
+  设定可见区域的分辨率。若修改成功则返回`true`（尝试将分辨率设定为与当前分辨率相同也可能会返回`false`），若失败则返回`false`。此操作会使得屏幕分辨率看上去降低，但实际分辨率仍然不变。超出指定区域左上角的字符只是隐藏不显示，此功能是为了能在屏幕外渲染或显示内容，并在需要时将它们复制到可视区域内。改动分辨率会将可见区域修改为与分辨率相同。
+\\
 - <del>`getSize(): number, number`
-  Gets the size in blocks of the screen the graphics card is bound to. For simple screens and robots this will be one by one.</del> Deprecated, use `screen.getAspectRatio()` instead.
+  获取显卡绑定到的屏幕的尺寸，大小为格。对单方块屏幕和机器人而言只有一个。</del> 已废弃，请改用`screen.getAspectRatio()`。
+\\
 - `get(x: number, y: number): string, number, number, number or nil, number or nil`
-  Gets the character currently being displayed at the specified coordinates. The second and third returned values are the fore- and background color, as hexvalues. If the colors are from the palette, the fourth and fifth values specify the palette index of the color, otherwise they are nil.
+  获取指定坐标处当前显示的字符。第二个与第二个返回值是前景和背景色，形式为16进制值。若颜色来自调色盘，第四个和第五个返回值将代表颜色的调色板索引号，否则为`nil`。
+\\
 - `set(x: number, y: number, value: string[, vertical:boolean]): boolean`
-  Writes a string to the screen, starting at the specified coordinates. The string will be copied to the screen's buffer directly, in a single row. This means even if the specified string contains line breaks, these will just be printed as special characters, the string will not be displayed over multiple lines. Returns `true` if the string was set to the buffer, `false` otherwise.
+  向屏幕写一条字符串，从指定坐标开始。字符串将会被直接复制到屏幕缓冲区，仅复制到单行。这意味着就算有换行符给定字符串也不会换行，换行符只会被以特殊字符的形式显示，字符串不会以多行显示。若字符串被成功传输给缓冲区则返回`true`，若失败则返回`false`。
-  The optional fourth argument makes the specified text get printed vertically instead, if `true`.
+  第四个参数为可选参数，若为`true`可以使给定文本竖行显示。
+\\
 - `copy(x: number, y: number, width: number, height: number, tx: number, ty: number): boolean`
-  Copies a portion of the screens buffer to another location. The source rectangle is specified by the `x`, `y`, `width` and `height` parameters. The target rectangle is defined by `x + tx`, `y + ty`, `width` and `height`. Returns `true` on success, `false` otherwise.
+ 将屏幕缓冲区的一部分复制到另一个位置。复制来源为矩形，由`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`
-  Fills a rectangle in the screen buffer with the specified character. The target rectangle is specified by the `x` and `y` coordinates and the rectangle's `width` and `height`. The fill character `char` must be a string of length one, i.e. a single character. Returns `true` on success, `false` otherwise.
+  用指定字符填充屏幕缓冲区中的一个矩形区域。目标矩形区域由`x`与`y`坐标以及矩形的`width`（宽度）和`height`（高度）决定。填充字符参数`char`必须是长度为1的字符串，即单个字符。若成功返回`true`，若失败返回`false`。
-  Note that filling screens with spaces (` `) is usually less expensive, i.e. consumes less energy, because it is considered a "clear" operation (see config).
+  请注意用空格（` `）填充屏幕通常耗能更少，因为此操作被视为"清除"操作（见配置文件）。
-Example use:
+使用例：
 ```lua
 local component = require("component")
-local gpu = component.gpu -- get primary gpu component
+local gpu = component.gpu --获取首选GPU组件
 local w, h = gpu.getResolution()
-gpu.fill(1, 1, w, h, " ") -- clears the screen
+gpu.fill(1, 1, w, h, " ") --清空屏幕
 gpu.setForeground(0x000000)
 gpu.setBackground(0xFFFFFF)
-gpu.fill(1, 1, w/2, h/2, "X") -- fill top left quarter of screen
+gpu.fill(1, 1, w/2, h/2, "X") --填充屏幕的左上四分之一区域
-gpu.copy(1, 1, w/2, h/2, w/2, h/2) -- copy top left quarter of screen to lower right
+gpu.copy(1, 1, w/2, h/2, w/2, h/2) --将屏幕的左上四分之一复制到右下
 ```
-GPU Color Depth
+GPU色深
 ==============
-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.
+色深（参见`gpu.setDepth`和`gpu.getDepth`）可以为1、4或8位，前景与背景色的色深可以不同。这三种色深分别可以提供2、16和256色。
-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.
+颜色值（传递给`gpu.setBackground`和`gpu.setForeground`的`number`型参数）会被解释为每通道8位的RGB颜色值（24位色）或某个调色板索引号。
-RGB Color
+RGB颜色
 -----------
-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).
+调用`setBackground`与`setForeground`时需要用到前景色与背景色，它们由`value`（数字型）和`is_palette`（布尔型）这一对变量定义（后者为可选）。
-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:
+若`is_palette`为`false`（或`nil`），`value`将被理解为24位RGB颜色值（0xRRGGBB），无论色深如何。但是给定颜色将会被取近似值为当前色深中与其最接近的颜色。单色的情况下，只有0会近似为0，任何非零值都会近似为1（代表使用设定好的那种颜色）。在4位色的情况下，会近似取调色盘中最接近的颜色。在8位色的情况下，会近似取可用的256种颜色种最接近的颜色。256种可用颜色如下表所示：
 {{:api:oc-256-color.png?nolink&768|}}
-Image by [Eunomiac](https://oc.cil.li/index.php?/topic/442-colors-what-determines-colors-i-code-vs-colors-i-get/)
+图片由[Eunomiac](https://oc.cil.li/index.php?/topic/442-colors-what-determines-colors-i-code-vs-colors-i-get/)制作
-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.
+当`is_palette`为`true`时，`value`将被理解为调色板中的索引号，范围为[0,15]。请注意，如果你从高色深切换到单色，系统会使用调色板中的颜色值来判定某种颜色转为单色后是0值还是非0值。在1位色深的情况下给定某种调色板颜色（即给定一个索引号和`true`）会出现错误。
-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.
+请注意，哪怕是在切换色深后，原始的颜色值对（代表数据的`number`值与代表是否为调色板颜色的`bool`型值）也会保留。实际在屏幕上渲染的颜色会被更新以符合新色深的限制，但是原始的24位RGB颜色值（或是调色板索引号）也不会丢失。例如，在处于1位色深模式下调用`gpu.getBackground`函数也会返回在先前的色深模式下指定的24位RGB颜色值。
-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 [[component:screen|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.
+显卡的内部有显存，你可以将他们以页的形式进行分配。你可以自定义页大小（宽与高都需要大于0）。每次分配都会从显卡的显存中扣除`宽度*高度`的大小。高级别GPU的显存比低级别的多。页缓冲区的工作方式类似于隐藏不渲染的[[component:screen:zh|屏幕]]，有其自己的宽度、高度和色深。GPU缓冲区支持的最大色深由GPU的等级决定。重启电脑将会释放所有的缓冲区。
-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.
+每个缓冲区页都有序号，GPU会查找下一个可用序号。序号零（0）有特殊用途，它是为屏幕保留的。无论GPU是否绑定到屏幕，你都可以分配页，设定它们是否启用，以及对它们进行读写。连接与断开屏幕，甚至是绑定到新屏幕，都不会释放GPU的页；而当电脑关机或重启时，页会被释放。每个GPU都有其独立的显存和页。
-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.
+对显存的更新操作（set、copy和fill等）几乎没有消耗。这些操作不会耗能，也不会额外消耗资源配额。每次直接组件调用（GPU方法即为直接调用）都只消耗很少的系统资源配额，但是GPU本身在显存更新操作中不会增加资源消耗。将显存传输到屏幕时会有一定的资源消耗，类似于屏幕更新时产生的资源消耗。传输脏的（修改过的）显存后备缓冲区需要一次性消耗一定的资源，消耗的量随源缓冲区的大小而增加。而后续从干净的后备缓冲区到屏幕的传输只需要消耗极少的资源。
 - `getActiveBuffer(): number`
-  Returns the index of the currently selected buffer. 0 is reserved for the screen, and may return 0 even when there is no screen
+  返回当前选中缓冲区的编号。0被保留给屏幕，且就算没有屏幕也有可能会返回0。
+\\
 - `setActiveBuffer(index: number): number`
-  Sets the active buffer to `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)
+  将活动缓冲区设定为`index`。0被保留给屏幕，且就算没有屏幕也可以设定。若编号无效则返回`nil`（0就算在没有屏幕的情况下也有效）。
+\\
 - `buffers(): table`
-  Returns an array of all current page indexes (0 is not included in this list, that is reserved for the screen).
+  返回包含当前所有页编号的数组（列表中不包含0，此编号保留给屏幕）。
+\\
 - `allocateBuffer([width: number, height: number]): number`
-  Allocates a new buffer with dimensions width*heigh (gpu max resolution by default). Returns the index of this new buffer or error when there is not enough video memory. A buffer can be allocated even when there is no screen bound to this gpu. Index 0 is always reserved for the screen and thus the lowest possible index of an allocated buffer is always 1.
+  分配一个大小为`width`x`height`的新页（默认大小为GPU的最大分辨率）。返回此缓冲区的编号，若剩余显存不足则报错。即使GPU未绑定到屏幕也可以分配缓冲区。编号0永久保留给屏幕，因此所分配缓冲区的编号最小从1开始。
+\\
 - `freeBuffer([index: number]): boolean`
-  Removes buffer at `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)
+  移除编号为`index`（默认为当前缓冲区编号）的缓冲区。若成功移除此缓冲区则返回`true`。如果你移除了当前选中的缓冲区，GPU会自动切换回编号0（为屏幕保留）。
+\\
 - `freeAllBuffers()`
-  Removes all buffers, freeing all video memory. The buffer index is always 0 after this call.
+   移除全部缓冲区，释放所有显存。在调用此函数后活动缓冲区编号一定为0。
+ \\
 - `totalMemory(): number`
-  Returns the total memory size of the gpu vram. This does not include the screen.
+  返回GPU的显存总量。此值不包括屏幕。
+\\
 - `freeMemory(): number`
-  Returns the total free memory not allocated to buffers. This does not include the screen.
+  返回未分配给缓冲区的空闲显存总量。此值不包括屏幕。
+\\
 - `getBufferSize([index: number]): number, number`
-  Returns the buffer size at `index` (default: current buffer index). Returns the screen resolution for index 0. Returns nil for invalid indexes
+  返回编号为`index`的缓冲区（默认为当前缓冲区）的大小。若编号为0则返回屏幕的分辨率。若编号无效则返回`nil`。
+\\
 - `bitblt([dst: number, col: number, row: number, width: number, height: number, src: number, fromCol: number, fromRow: number])`
-  Copy a region from buffer to buffer, screen to buffer, or buffer to screen.
+  将一个矩形区域从缓冲区复制到缓冲区，从屏幕复制到缓冲区或从缓冲区复制到屏幕。
-  Defaults:
+  默认值：
-  * dst = 0, the screen
+  * dst = 0，代表屏幕
   * col, row = 1,1
-  * width, height = resolution of the destination buffer
+  * width, height = 目标缓冲区的分辨率
-  * src = the current buffer
+  * src = 当前缓冲区
   * fromCol, fromRow = 1,1
-  bitblt should preform very fast on repeated use. If the buffer is dirty there is an initial higher cost to sync the buffer with the destination object. If you have a large number of updates to make with frequent bitblts, consider making multiple and smaller buffers. If you plan to use a static buffer (one with few or no updatse), then a large buffer is just fine.
+  bitblt（位块传输）在反复进行时应当执行得很快。若缓冲区是脏的，那么与目标对象同步缓冲区的初始成本会更高。如果你需要大量进行更新，导致频繁进行位块传输，那么可以考虑分配数量多而尺寸小的缓冲区。如果你希望使用一个静态缓冲区（很少或不进行更新），那么分配大的缓冲区即可。
-  Returns true on success
+  操作成功后会返回`true`。
 目录
 ----
 {{page>component:contents:zh&noheader&noeditbutton&nouser&nofooter}}