Differences

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

--- component:gpu [2018/11/25 16:48]
evg-zhabotinsky
+++ component:gpu [2020/05/18 11:44]
payonel
@@ Line 11: / Line 11: @@
 Callbacks:
+- [[component:gpu#video_ram_buffers|Video Ram Buffers]]
+  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 (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'.
@@ Line 97: / Line 100: @@
 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 [[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.
+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.
+- `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
+- `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)
+- `buffers(): table`
+  Returns an array of all current page indexes (0 is not included in this list, that is reserved for the screen).
+- `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.
+- `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)
+- `freeAllBuffers()`
+  Removes all buffers, freeing all video memory. The buffer index is always 0 after this call.
+- `totalMemory(): number`
+  Returns the total memory size of the gpu vram. This does not include the screen.
+- `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
+- `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
+  * col, row = 1,1
+  * width, height = resolution of the destination buffer
+  * src = the current buffer
+  * 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.
+  Returns true on success
 ----
 {{page>component:contents&noheader&noeditbutton&nouser&nofooter}}