Extended Graphics Library (libgs)

Provides functions for a 3D graphics system built on libgpu and libgte.

This is an old revision of this page, as edited by RemmyLee at 03:05, 23 October 2026. Edit this revision | Latest revision

Overview

The Extended Graphics Library (libgs) integrates the 2D and 3D graphics systems of libgpu and libgte. It is designed for the standard graphics formats made by the PlayStation authoring tools. TIM stores images with their resolution, colors and color lookup tables, TMD stores objects with scale and texture address information, and HMD was added in library version 4.0.¹

libgpu and libgte process data polygon by polygon, while libgs processes objects, which are groups of polygons. 3D programs are therefore easy to prototype, and attributes added to objects create special effects. libgs has more overhead than libgpu and libgte. However, its architecture is open, so a finished program can replace parts of it with user functions through a jump table.¹

A program that uses libgs links with libgs.lib and includes libgs.h.¹

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

Features

The main features of libgs are the following:¹³

Coordinate Systems

GsCOORDINATE2 describes a coordinate system of libgs. The systems form a hierarchy with the world coordinate system at the top, and each is integrated from the lower level to the higher. The matrix of a GsCOORDINATE2 describes the coordinate system relative to its parent. X, Y and Z are each 32 bits, and a work area speeds up the calculation. GsInitCoordinate2() initializes the structure, and its members may also be set directly.³

Rotation is executed first and translation second. When RotMatrix() creates the rotation matrix, the order of rotation is Z first and X last.³

The flg member set to 1 marks a system whose local-to-world matrix is already in workm, so it is not calculated again. A program that rewrites a GsCOORDINATE2 therefore sets flg to zero. A change to a parent applies to all its children automatically, and their flags need not be cleared.⁴

Objects

Objects are handled by 3D object handlers. The basic handler is GsDOBJ2, and the others are GsDOBJ3 and GsDOBJ5. The coord2 member of GsDOBJ2 points to the coordinate system of the object, so the object moves when that GsCOORDINATE2 changes. GsLinkObject4() sets the tmd member of a GsDOBJ2 to the TMD object read in.⁴⁵

When the coord2 of object 2 is made a child of the GsCOORDINATE2 of object 1, moving object 1 also moves object 2, while moving object 2 does not affect object 1. The bits of the attribute member control material attenuation, the lighting mode, near clipping, back clipping and automatic division, together with display or non-display.⁴⁵

Viewing System

The screen shows a projection of 3D space onto a window at a given distance in front of the viewpoint. GsSetRefView2() sets the viewpoint from a GsRVIEW2, which gives the viewpoint and a reference point, and GsSetView2() sets it from a GsVIEW2, which gives the transformation matrix directly. With the world as the parent the view is an objective camera, and with the coordinate system of an object it is a subjective camera for that object.⁵

GsSetProjection() sets the projection (h), which is the distance between the viewpoint and the screen. The screen has the size of the display resolution, so a 640 x 480 display gives a 640 x 480 screen. When the display does not have square dots, the vertical is adjusted. In 640 x 240 mode an object is displayed at 1/2 height. GsInit3D() initializes the 3D service and puts the origin at the center of the screen. A large projection gives a narrow image angle close to parallel projection, and a small projection a wide angle with strong perspective.⁵⁶

Light Sources

libgs has up to 3 parallel light sources. With a parallel light the brightness of a polygon depends only on the light and the angle of the polygon, and the light is set by its direction and color in a GsF_LIGHT structure with GsSetFlatLight().⁶

Ambient light shows the shape of an object where no light strikes it. GsSetAmbient(ONE/2, ONE/2, ONE/2) makes unlit parts half as bright as lit parts, where ONE is the fixed-point 1. Higher ambient values make the image warmer and lower values cooler.⁶

Depth cueing (fog) dims distant objects. It works on all non-textured polygons, but on texture-mapped polygons only when the color is black. GsSetLightMode(1) or GsSetLightMode(3) turns it on, and GsSetFogParam() sets the background color with a GsFOGPARAM structure. A whitish color gives fog and black gives a night effect.⁶⁷

Material lighting makes an object look metallic with a steeper light attenuation curve. It is selected with GsSetLightMode(2) or GsSetLightMode(3) and the attenuation bits of the attribute member, but the manual states that this is not possible in the current version.⁷

Ordering Tables

The PlayStation removes hidden surfaces by Z sorting, which the ordering table (OT) speeds up. An OT is a kind of Z ruler in memory, and each graduation may hold any number of polygons. Each polygon hangs at the graduation of its Z value, and the polygons at the far end of the OT, with the largest Z, are drawn first.⁷

The GsOT structure handles an OT in libgs. Its org member points to the actual OT, its length member gives the number of Z graduations, and each graduation is a GsOT_TAG. GsClearOt() initializes the OT before every sort, since only an initialized OT can be sorted again, and its arguments are offset, point and the OT handler.⁷

GsSortOt() sorts one OT into another. The point member gives the representative Z of the OT. Local OTs for each object sorted into one OT sort the scene by objects, which helps when the order is already known. Two OTs drawn to the two halves of the drawing area with different viewpoints give a split screen.⁷⁸

An OT uses much memory, and a lower resolution saves memory but causes flicker. When the Z values of all polygons are above a known value, that value can be passed to GsClearOt() as offset, and the OT does not store the part below it.⁸

Z sorting can draw polygons in the wrong order and make them flicker, most often with a deep polygon, which is sorted by one average Z. Dividing the polygons avoids this at the cost of more polygons. Sorting by object units avoids it when the order of the objects is clear.⁸

Double Buffers

An OT cannot be changed while it is drawn, so two OTs are prepared and the program sorts into the one not being drawn. The display has a double buffer in the same way. Switching outside the vertical blank disturbs the screen. The screen being displayed and the screen being drawn are therefore separate. GsDefDispBuff() defines the two buffers, GsSwapDispBuff() switches them and GsGetActiveBuff() returns the buffer being drawn.⁸

Double buffering moves the display area in the frame buffer, so drawing needs an offset. The third argument of GsInitGraph() adds the offset either in libgte, when the packets are calculated, or in libgpu, when the frame buffer is drawn. The manual recommends the libgpu method with libgpu functions. In interlace mode with 480 lines the even and odd lines double the buffer. Both arguments of GsDefDispBuff() then name the same buffer.⁹

Clipping

libgs clips in two ways. Two-dimensional clipping clips in screen coordinates to any rectangle of the frame buffer. GsSetClip2D() sets the area in an internal variable and GsSetDrawBuffClip() makes it effective, and the area is switched with the double buffer, so that an oversized polygon does not damage the other buffer. Three-dimensional clipping clips by the distance from the viewpoint, and libgs has the following defaults:⁹

Polygons close to the viewpoint, such as the road of a racing game, become very large, and clipping them by polygon leaves holes. Automatic division clips them smoothly at the near clip plane, but it is a heavy load and is used only when needed.¹⁰

Packet Buffers

libgs has three packet creation functions, GsSortObject3(), GsSortObject4() and GsSortObject5(), and two packet buffers. The preset packet buffer holds packets made ahead of time for GsSortObject5() and GsDOBJ5, and its size is fixed by the model. GsPresetObject() fills it once, and its return value shows how far the buffer is used. Preset packets do not use the run-time buffer, except when automatic division is on.¹⁰

The run-time packet buffer holds the packets that GsSortObject4() and functions such as GsSortSprite() make during execution. GsSetWorkBase() sets its start and GsGetWorkBase() returns the current pointer. The amount used per frame depends on the number of polygons.¹⁰

Preset packets need not be rewritten every frame, which saves work such as writing the U and V values. The PMD format holds both the modeling data and the preset packets. A packet group begins with header 0, whose upper 8 bits give the packet type and lower 24 bits point to the next group. Header 1 follows with the number of packets, each packet is doubled for the double buffer, and a terminator with a zero address ends the list.¹⁰¹¹

TMD Sort

TMD data may mix polygon types at random. When the packets are made at run time the decode routines then swap out of the I-cache, and the processor cannot keep up. The TMD sort orders the polygons by type at authoring time with TMDSORT.EXE, and GsSortObject4() and GsSortObject5() are faster with sorted data.¹¹

Packet Creating Functions

GsSortObject3() creates packets from PMD data with the GsDOBJ3 handler. GsLinkObject3() first joins the data to the handler, and TMD2PMD.EXE converts TMD to PMD. GsSortObject4() is the most general function and uses sorted TMD data with the GsDOBJ2 handler. It converts the object with the local screen matrix from GsSetLsMatrix() and the light matrix from GsSetLightMatrix(), sorts it and allocates it to the OT. GsSortObject5() uses preset packets with GsDOBJ5 and sorted TMD data.¹¹¹²

The functions support the following attributes, where the efficiency is the measured value for 10 x 10 flat triangles:¹²

GsSortObject4() is more efficient than GsSortObject3() and less efficient than GsSortObject5().¹²

Packet Area

The size of the packets depends on the type and number of polygons, so only a rough estimate of the needed area can be made. A packet area that is too small overwrites the memory behind it. GsGetWorkBase() returns the area in use, from which a program can judge the danger of overflow. With automatic division a packet area from GsSetWorkBase() is needed, also with GsSortObject5(), because divided packets grow.¹²¹³

Drawing runs in the background, and the packets being drawn must not be destroyed. Two packet areas are therefore prepared as a double buffer.¹³

Drawing

GsDrawOt() starts drawing, which runs in the background. The drawing area changes each time GsSwapDispBuff() is called, and enough time must be left for the drawing to finish. GsSortClear() registers a screen clear primitive in the OT with an RGB color, since the drawing area still holds the image of two frames before. A frame is processed in the following order:¹³

1. Select the buffer to use.
2. Clear the OT.
3. Perspective transformation and Z sort.
4. Wait for the vertical blank.
5. Start drawing the OT.

Jump Tables

GsSortObject4() and GsSortObject5() dispatch the attributes and preset data to 64 low-level functions, and few applications use all of them. GsSortObject4J() and GsSortObject5J() take the low-level functions from a table in a GsFCALL structure, organized by polygon type, division and light source mode. Only the functions named in the table become part of the program, which makes the code smaller. A user function in the table can also replace a library function and add effects such as material attenuation or reflection mapping.¹⁴

A call to an entry without a pointer is a bus error. libgte therefore provides dummy (dmy) functions, which print their own name when an unexpected type is called.¹⁴

Scratch Pad

GsSortObject4(), GsSortObject5() and their J versions take a scratch pad address. The scratch pad is a feature of the CPU that gives fast access to up to 1 KB of data, and libgs uses it in automatic division (GsDIV1 to GsDIV5) to improve speed. Without automatic division it is not used. The use in bytes is the following:¹⁵

The library extends its area downward from the given base address, so the user program can share the scratch pad by using the area above it.¹⁵

Mip-Map

libgs supports mip-mapping, which switches the texture of a textured quadrilateral by the size of the polygon. The texture cache then hits more often and drawing takes less time. The low-level functions of GsSortObject4J() whose names end in M, in the GsTMDfast, GsTMDdiv and GsA4div groups, support it.¹⁵¹⁶¹⁷

The textures come in four sizes, 1, 1/4, 1/16 and 1/64, and all four lie in the same texture page. The size to use is found from the outer product of the polygon, and the vertices of the polygon are ordered 0 and 1 across the top and 3 and 2 across the bottom.¹⁷¹⁸

Structures

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

libgs has the following structures:¹⁹

Functions

libgs has the following functions:²⁰

Macros

libgs has the following macros:²¹

References