Basic Graphics Library (libgpu)

Provides functions for drawing primitives such as sprites, polygons and lines.

Overview

The Basic Graphics Library (libgpu) is a low-level function library for drawing primitives such as triangles, rectangles and sprites with the GPU. It provides system functions that control the whole graphics system, frame buffer access functions that read and write the frame buffer directly, and primitive functions that initialize primitive structures and set the texture page. It also provides ordering table functions, which register primitives in an ordering table and draw them, and synchronization functions, which wait for the vertical blank period and for the end of drawing.¹²

A program that uses libgpu links with libgpu.lib and includes libgpu.h.³

This library is part of the run-time library that Sony distributed with the Psy-Q development tools.⁴

Graphics System

The graphics system consists of the GPU and a 1 MB frame buffer together with the GTE. The frame buffer holds the current display, a drawing area, textures and color tables, and the GPU can use the results of GTE calculations in its commands.¹

The GPU draws into the drawing area of the frame buffer by executing instruction strings (primitives) stored in main memory, and the data structures of libgpu correspond to the primitives of the GPU hardware. The video signal is made continuously from the frame buffer, so rewriting the frame buffer up to 60 times per second produces moving images. The graphics system has no separate background plane.⁵

Frame Buffer Addressing

The frame buffer is a bitmap 1024 pixels wide and 512 pixels tall with 16 bits per pixel. Its total size is therefore one megabyte (1024 x 512 pixels x 2 bytes per pixel). It stores texture patterns and color lookup tables (CLUTs) as well as the drawing and display areas.⁵

A pixel is addressed by X from 0 to 1023 and Y from 0 to 511. Each pixel has 5 bits for blue, 5 bits for green and 5 bits for red, and the high-order bit is the semi-transparent flag (STP):⁵⁶

Display Area and Drawing Area

The display area is the rectangle of the frame buffer that is shown on the screen. Its size depends on the display mode, from 256 x 240 to 640 x 480 (709 x 488 with overscan), and the following values can be combined:⁶

The heights assume NTSC. PAL is described under PAL Format below.⁶

The drawing area is the rectangle of the frame buffer into which primitives are drawn, and it may be any size that fits in the frame buffer. When the drawing area overlaps the display area, the drawing shows on the screen. A program therefore prepares two areas of the same size, draws into one while the other is displayed, and switches them in the vertical blank period to avoid flashing and tearing.⁶

Drawing Environment

A DRAWENV structure holds the drawing environment, which is the set of settings for two-dimensional drawing such as the position of the drawing area and the drawing offset. SetDefDrawEnv() sets the members of a DRAWENV, PutDrawEnv() makes it the current drawing environment and GetDrawEnv() returns the current one. DRAWENV has the following members:⁶⁷

A new drawing environment set with PutDrawEnv() during drawing does not affect the primitive being executed or the rest of the current list. It takes effect with the next drawing operation. A program can also change all or part of the drawing environment in the middle of drawing by registering a special primitive in the ordering table.⁸

Display Environment

A DISPENV structure holds the display environment, which is the set of display settings such as the position of the display area. SetDefDispEnv() sets its members, PutDispEnv() makes it current and GetDispEnv() returns the current one. DISPENV has the following members:⁷

A smaller screen area gives an underscan and a larger one an overscan, but the size of each pixel does not change. Settings in the display environment take effect at once. Consequently, the display position and area can change while drawing goes on in the background.⁷⁸

Double Buffer

A double buffer uses two areas of the frame buffer that change places between the display environment and the drawing environment. For example, with buffer 0 at (0, 0) to (320, 240) and buffer 1 at (0, 240) to (320, 480), the environments are set as follows:⁸

In 640 x 480 interlace mode the frame buffer has no room for two buffers, so a single buffer is used for both drawing and display. In each 1/60 second field the display shows either the odd or the even lines. With dfe set to 0 the GPU then draws only on the lines that are not being displayed, which is equivalent to double buffer switching, provided that drawing completes within 1/60 second.⁹

Blocking and Non-Blocking Functions

A blocking function completes its processing before it returns. Several drawing functions take a long time, and these are processed in the background and return without waiting for completion. They are called non-blocking functions:⁹

All other functions are blocking functions, and DrawSync() detects or waits for the end of the non-blocking ones. Up to 64 non-blocking requests may wait in the queue. When DrawOTag(ot1) is called before DrawOTag(ot0) has finished, the request is registered in the queue and the function returns at once, and a 65th request blocks until the queue has room.⁹¹⁰

Primitives

A primitive (or packet) is the smallest command the graphics system handles. Primitives are data structures created in main memory, and the CPU and the GPU may refer to them at the same time. Drawing primitives draw pixels in the frame buffer. Special primitives change parameters of the GPU, such as the clipping area and the texture page, during drawing, and do not change the frame buffer themselves.¹⁰

There are four types of drawing primitive: polygon, line, sprite and tile. A polygon has 3 or 4 sides, flat or Gouraud shading and texture mapping on or off, which gives eight polygon primitives. Tiles are drawn in a solid color, while sprites are texture-mapped.¹⁰¹¹

Special primitives change all or part of the drawing environment during drawing:¹¹

Primitive Format

Primitives are C structures, and the first two words of every drawing primitive are the same. The tag word links primitives into a list so that several primitives execute together. Its top 8 bits hold the number of GPU words in the packet and its bottom 24 bits point to the next primitive. The code member holds the primitive identifier, which is a value reserved for the library.¹¹¹²

The members of POLY_FT4 show the general form:¹²

A primitive must be initialized before it is executed. The initializing function of each primitive type, such as SetPolyFT4(), sets the tag, code and pad members, and the other members may then be written freely. libgpu.h defines macros for setting the members.¹²

Between initialization and execution, SetSemiTrans() sets the semi-transparent attribute and SetShadeTex() inhibits shading of a texture. MargePrim() joins two primitives into a single new primitive of at most 16 long words. AddPrim() and DrawPrim() handle the result like any other primitive.¹³

DrawPrim() executes one primitive. Because a primitive is drawn on top of the primitives executed before it, the order of execution sets the display priority. Many primitives are therefore usually registered in an ordering table and executed together with DrawOTag().¹³

Primitive Drawing Rules

The GPU draws the pixels whose centers lie inside the boundary of the primitive. For a pixel center on the boundary, the pixel is drawn when the inside lies to its right or below it, and not drawn when the inside lies to its left or above it. Consequently, POLY primitives do not draw their extreme right and lowest points, and pixels along the edge shared by adjacent polygons are not drawn twice.¹⁴

Ordering Tables

The ordering table (OT) controls the order of execution of many primitives. It is an array of pointers to primitives in main memory and is a form of list designed for inserting the primitives of a three-dimensional scene. Its size is the number of priority levels needed. An OT of 256 entries gives 256 levels of priority.¹⁴

ClearOTag() initializes the array so that each entry points to the next and the last entry holds a terminator. AddPrim() or AddPrims() registers primitives in the entries, and DrawOTag() executes them. Because DrawOTag() is a non-blocking function, the CPU continues its work while the GPU draws.¹⁴

The primitives at the start of the OT are executed first and therefore appear furthest back. Several primitives may share one entry, and in that case the primitive registered last in the entry executes first. Special primitives registered in the OT affect the primitives that follow them.¹⁵

A program may also chain primitives to each other without an OT and execute the list with DrawOTag(). Such a list loses the flexibility of the OT.¹⁵¹⁶

Z Sorting

An OT implements Z sorting, which removes hidden surfaces by ordering the primitives by depth. The position of a primitive in the OT is computed from its Z value. Many libgte functions such as RotTransPers() return this index (otz) together with the coordinate transformation. The otz value is the Z coordinate divided by 4, so an OT of 1/4 the dynamic range of Z is sufficient.¹⁶

Because otz is large for distant objects, it would have to be inverted before use as an index. ClearOTagR() avoids this by initializing the OT in reverse order, which also changes the other calls:¹⁶

The normal OT suits two-dimensional sprite games and the reverse OT suits three-dimensional graphics. The reverse OT is initialized by a high-speed hardware function and the normal OT by software, so a large OT is initialized much faster in reverse order.¹⁷

To display a three-dimensional object, the object is broken into triangles and quadrilaterals, and the geometry library converts each vertex to screen coordinates. The screen position is h x Sx / Sz and h x Sy / Sz, where h is the distance from the viewpoint to the screen, and the OT index is Sz / 4.¹⁷

AddPrims() inserts an entire OT into another OT. This serves when more than one hierarchical coordinate system is in use. The link of the last entry of the child OT is replaced in this case, so no primitive may be registered in that entry.¹⁸

Reset

ResetGraph() resets the graphics system. Every level stops the drawing command in progress, cancels the requests in the queue and enters wait status. The levels differ in what they keep:¹⁸

Level 0 is a complete reset that is executed once when the program starts. It sets the display mode to 256 x 240 and masks the display. Level 1 is used often when switching the double buffer. Level 3 is used at the start of a child process started with Exec(), because it switches the callbacks without disturbing the display set by the parent.¹⁸

Synchronization

A program detects the end of background work by polling or by callbacks. DrawSync() and VSync() poll as follows:¹⁹

DrawSyncCallback() defines a function called when a non-blocking drawing operation such as DrawOTag() completes. VSyncCallback() defines a function called at the start of each vertical blank period, which can switch the display buffers and perform other work that must be synchronized with the display. VSync() and VSyncCallback() are part of libetc.¹⁹²⁰

To avoid flicker, the drawing and display buffers are switched at the vertical synchronization with DrawSync() and VSync(). Drawing at 60 frames per second is achieved only when the CPU work of each frame ends within 1/60 second.²¹²²

Packet Double Buffer

The memory for the OT and primitives is the packet buffer. The CPU cannot change the primitives and the OT until the graphics system has finished with them, so a single packet buffer prevents the CPU and the GPU from working in parallel. With two packet buffers, the CPU generates the OT and primitives in one while the GPU executes the other, and the two exchange tasks each frame. This is the packet double buffer.²²²³

In interlace mode the drawing must be updated every 1/60 second regardless of the calculation time. A callback can then issue DrawOTag() in each field, and when the new OT is not ready in time the previous OT is drawn again.²³²⁴

Texture Mapping

Texture mapping maps a two-dimensional bitmap called a texture pattern onto triangles and quadrilaterals. Textures are stored in texture pages, which are 256 x 256 bitmaps in the frame buffer outside the display and drawing areas. The X coordinate of a texture page is a multiple of 64 and the Y coordinate a multiple of 256, so texture pages may overlap horizontally.²⁴

Each primitive may use one of three texture pattern modes:²⁴

In 16-bit mode the texel is used directly. It has 15 bits of RGB and 1 semi-transparent bit. The 4-bit and 8-bit modes use each texel as an index into a CLUT, which is a horizontal row of 16-bit pixels in the frame buffer with 16 or 256 entries. A 16-bit word holds one 16-bit texel or two 8-bit texels or four 4-bit texels. Consequently, a 256 x 256 texture page occupies from 256 x 256 (16-bit mode) to 64 x 256 (4-bit mode) of the frame buffer.²⁴

LoadImage(), MoveImage() and StoreImage() address the frame buffer in 16-bit pixels, so the width of a 4-bit texture is divided by 4 and the width of an 8-bit texture by 2. An 8-bit texture is therefore a multiple of 2 pixels wide and a 4-bit texture a multiple of 4. LoadTPage() and LoadClut() load a texture page and a CLUT and return their IDs. Each primitive sets its own CLUT, several textures may share one CLUT, and a 4-bit texture can use any 16 entries of a larger CLUT.²⁵

Unlike a polygon, a sprite primitive (SPRT) does not specify a texture page. The current texture page must therefore be correct when sprites execute. The drawing environment sets the first current texture page and a DR_MODE primitive changes it.²⁵²⁶

Transparent and Semi-Transparent Pixels

Bit 15 of each texel, or of its CLUT entry in 4-bit and 8-bit mode, is the semi-transparent (STP) bit. A texel of 0x0000 is transparent and is not drawn. A texel with STP set is semi-transparent when the primitive is set semi-transparent with SetSemiTrans(), and a texel with STP clear and a non-zero color is always opaque:²⁶

A primitive without texture mapping may also be set semi-transparent, and all its pixels are then semi-transparent. Semi-transparent drawing is much slower, because the existing pixels in the frame buffer must be read, processed and written back. The rate is chosen per primitive from the following, through the texture page or a DR_MODE primitive, and a brightness above the maximum is clipped:²⁶

Texture Brightness

The r, g and b members of a textured primitive scale the brightness of its texels. With all three set to 128 the pixels are drawn at the brightness of the source texture, and a result above 255 is clipped to 255. A program sets r, g and b when it initializes a textured primitive, or turns the scaling off with SetShadeTex().²⁶²⁷

Texture Window

A texture window is part of a texture page within which a texture pattern repeats. It is set by the tw member of DRAWENV or by a DR_MODE primitive. The normal window is (0, 0) to (255, 255), which does not repeat, and a smaller window repeats the texture as needed. The U and V coordinates of the primitive must lie inside the window.²⁷

Texture Cache

The GPU must read the texture pattern from the frame buffer to draw a textured polygon. To speed this up, it has a 2 KB texture cache, and texels that are already in the cache are read from it much faster than from the frame buffer. The cache uses two-dimensional addresses like the frame buffer, and its size depends on the pixel mode:²⁷²⁸

A texture page is divided into cache blocks the size of the cache, so in 4-bit mode a page has 16 blocks. Each block is divided further into cache entries, and there are always 256 entries:²⁹³⁰

An entry holds 4 short words, so a 4-bit entry holds 16 texels, and each entry also holds the block number that decides a hit or a miss. Because each entry stores its own block number, texels of different blocks stay in the cache together as long as their entry numbers differ. For example, the cache holds all the texels of the rectangle (16, 16) to (79, 79) at once. The rows (8, 8) to (15, 8) and (64, 8) to (71, 8) use the same entries. Consequently, the cache cannot hold all the texels of the rectangle (8, 8) to (71, 71) at once.³¹³⁰

Rendering Speed

DrawSync() shows whether the CPU or the GPU limits the speed. When the CPU is the bottleneck DrawSync() returns at once, and when the GPU is the bottleneck it blocks, and the time it waits measures the GPU latency. In the latter case optimizing the program code does not help.²⁸

Rendering speed depends on the number of reads and writes to VRAM. A larger primitive writes more VRAM and takes longer, and semi-transparent drawing is slower than opaque drawing because it also reads. For the same area, TILE is fastest, followed by POLY_F and POLY_G and then the textured primitives. A texture cache hit is always faster, and on a miss 4-bit textures are faster than 8-bit and 8-bit faster than 16-bit.²⁸³²

The access cycles of the frame buffer are the following:³²

A 4-bit texel word holds four texels and an 8-bit word two, so one read fetches several texels. With 1:1 mapping, primitives of 100 x 100 pixels therefore take the following cycles:³²³³

A texture in the cache is drawn at the same speed in every mode. Reducing a texture by half horizontally does not halve the time, while an enlarged texture draws faster because the same texels are used several times. During clipping, the parts of a polygon to the left of and above the drawing area generate empty cycles, including empty texture reads.³³²⁹

Primitive Division

The PlayStation maps textures with an affine transformation, u = a0 x x + a1 x y + a2 and v = b0 x x + b1 x y + b2. This is correct only when the depth within the polygon is nearly constant. Consequently, a large quadrilateral with large depth changes, such as a ground surface, is drawn with a bent diagonal line.³⁰

A large textured primitive also gains nothing from the texture cache. In 4-bit mode texels 64 apart share an entry. A primitive whose U or V spans more than 64 texels therefore always misses the cache. In the worst case, with the U and V directions at 90 degrees to X and Y, the speculatively read texels are flushed before use and the drawing speed halves. A large primitive also produces more empty clipping cycles, since it is less often entirely outside the drawing area.³⁰³⁴

Dividing a large primitive at its midpoints before drawing solves almost all of these problems. Perspective is calculated correctly at each new vertex, the U and V spans fall within the cache size, and more of the divided pieces fall wholly outside the drawing area.³⁴³⁵

Debug Environment

SetGraphDebug() sets the debug mode, in which each function checks its data as far as possible and prints a return code and the contents as a debug string. The Dump functions also print the contents of structures, and the Fnt functions display the strings on screen.³⁵

libgpu has no functions for PlayStation data formats such as TIM and TMD. These formats are handled by libgs. OpenTIM(), ReadTIM(), OpenTMD() and ReadTMD() read the headers of TIM data and the polygons of TMD data for debugging the data only.³⁵

Texture Polygon Coordinates

POLY primitives do not draw their right and bottom edges. Without this rule the edges shared by four adjacent polygons would be drawn twice, which would show in semi-transparent mode. As a consequence, an 8 x 8 POLY_FT4 must be given (x, y) = (0, 0) to (8, 8) and (u, v) = (0, 0) to (8, 8) to show all 8 x 8 texels. With (u, v) = (0, 0) to (7, 7) the last row and column of the texture are lost.³⁶³⁷³⁸

The same rule shifts a texture one dot when it is inverted or rotated by 90 degrees or more, and loses the right and bottom lines when a texture is enlarged two times or more. The lines at u = 255 and v = 255 cannot be shown in that case at all, because U and V are 8 bits and 256 overflows to zero. Subtracting 1 from U and V avoids these problems, but the texture is then drawn at 16:15 for a 16 x 16 pattern or 8:7 for an 8 x 8 pattern.³⁹⁴⁰⁴¹

PAL Format

The descriptions above assume NTSC. PAL differs as follows:⁴¹

The PAL field rate is 50 Hz, so the maximum display rate is 50 frames per second, and a program timed by VSync runs at 5/6 of its NTSC speed. Its timing is therefore adjusted by 6/5. A PAL display also shows more lines, so the NTSC display area leaves the top or bottom of the screen dark. SetVideoMode(MODE_PAL) enables PAL mode, and the screen member of DISPENV centers the display.⁴¹⁴²

Frame Buffer Update Timing

The display area may be updated at a rate different from the 1/60 second video rate. However, an update at an irregular rate makes the screen flicker, so buffer switching is synchronized with the vertical sync by a VSync(0). When the time to make a frame lies close to 1/60 second, the frame rate jitters between 60 and 30 frames per second and objects move unnaturally. VSync(2) fixes the rate at 30 frames per second. In the same way VSync(3) gives 20 frames per second and VSync(4) gives 15.⁴²⁴³

A program whose frame rate varies times its motion with an absolute counter such as VSync(-1) or RCnt3 instead of the frame count, so that objects move at the same speed when frames are skipped. In interlace mode, however, both calculation and rendering must end within 1/60 second, so VSync has priority over DrawSync and ResetGraph(1) cancels drawing that overruns the field.⁴³⁴⁴

VSync(1) returns the time since the last VSync(0) or VSync(n) in horizontal sync units. The value right after VSync(0) is not always close to 0, because sound callbacks and controller drivers run during the vertical blank.⁴⁴

Interlace Mode Fields

In the interlace single buffer mode with 480 lines, the GPU draws only the even lines while an odd field is displayed and only the odd lines while an even field is displayed. During the vertical blank, however, the GPU always treats the field as even. VSyncCallback() runs at the start of the vertical blank, so the primitives drawn first, usually the background, reach only the even field and half of the background is not cleared.⁴⁴⁴⁵

Rendering must therefore start after the vertical blank ends. An H-Sync callback on RCnt2 can start it. GetODE(), introduced in library 3.7, returns the field that the GPU recognizes, which is not always the field of the video output.⁴⁵

Structures

In the tables below, Introduced is the run-time library version that added the item.⁴⁶

libgpu has the following structures:⁴⁶

Functions

libgpu has the following functions:⁴⁷

Macros

libgpu has the following macros:⁴⁸

References