1vgagl(7) Svgalib User Manual vgagl(7)
2
6 vgagl - a fast framebuffer-level graphics library based ion svgalib
7
9 0. Introduction
10 1. How to use vgagl
11 2. Description of vgagl functions
12 3. Macros defined in vgagl.h
13
16 This is a fast framebuffer-level graphics library for linear 1, 2, 3
17 and 4 byte-per-pixel modes (256-color, hicolor, truecolor). It uses a
18 limited number of functions from svgalib (libvga) for low-level hard‐
19 ware communication (the library is included in the svgalib shared
20 image).
21 In particular, svgalib(7) maps the 64K VGA frame buffer window, and
23 this library directly addresses the buffer. For SVGA modes that use
24 more than 64K of screen memory, SVGA paging is required when writing to
25 the physical screen; this is done automatically for most functions (at
26 a certain cost).
27 Alternatively, any number of virtual screens of any type in system mem‐
29 ory can be used, which can then be copied to the physical screen. There
30 is also support for 4 bytes per pixel framebuffers (and copying them to
31 a 3 bytes per pixel context), and limited planar 256 color mode support
32 (copyscreen, aligned putbox).
33 The planar 256 color modes (available on all VGA cards) can now be used
35 with a virtual screen, which is copied to the physical screen (with
36 optional page-flipping).
37 Bitmaps are raw, with one (or more) bytes per pixel (like pixmaps in
39 X), stored in row-major order. They are usually manipulated with the
40 getbox and putbox functions.
41 vgagl does also make use of the graphic cards accelerator (if it is
43 supported) in some situations.
44 A graphics context is just a structure that holds the size of the asso‐
46 ciated graphics screen, how it is organized, clipping status etc. You
47 can define a custom virtual (system memory) graphics context of any
48 size with the setcontextvirtual function. All operations work on the
49 current context.
50 Any questions, bug-reports, additions, suggestions etc. are welcome.
52
55 Programs that use vgagl must #include <vgagl.h>. Linking must be done
56 with -lvgagl -lvga.
57 Functions in the vgagl library have the prefix gl_*. To initialize
59 vgagl, the graphics context must be set. Example:
60 vga_setmode(G320x200x256);
62 gl_setcontextvga(G320x200x256);
63 In this example, the context is set to the physical screen. The context
65 can be saved (only the screen type, not the contents) into a variable,
66 e.g.
67 GraphicsContext physicalscreen;
69 gl_getcontext(&physicalscreen).
70 To define a virtual screen in system memory, use gl_setcontextvgavir‐
72 tual(3):
73 gl_setcontextvgavirtual(G320x200x256)
75 which allocates space for a screen identical to 320x200x256 graphics
77 mode, and makes this virtual screen the current graphics context.
78 The virtual screen can now be copied to the physical screen as follows:
80 gl_copyscreen(&physicalscreen);
82 Note that with a virtual screen in system memory, it is possible to add
84 fast X-Window support to a program, using MITSHM to copy the frame‐
85 buffer to the screen window.
86
89 Context management
90 gl_getcontext(3), currentcontext(3)
91 get the current graphics contents..
92 gl_setcontext(3)
93 set a previously saved context.
94 gl_setcontextvga(3)
95 set the context to the physical screen.
96 gl_setcontextvgavirtual(3)
97 set the context to a virtual mode.
98 gl_setcontextvirtual(3)
99 define a virtual context.
100 gl_allocatecontext(3)
101 allocate a graphics context.
102 gl_freecontext(3)
103 free a virtual screen.
104 gl_setcontextwidth(3), gl_setcontextheight(3)
105 set the dimension of a context.
106 Drawing primitives
108 gl_clearscreen(3)
109 clear the screen.
110 gl_rgbcolor(3)
111 return pixel value corresponding to an rgb color.
112 gl_setpixel(3), gl_setpixelrgb(3)
113 draw a pixel.
114 gl_getpixel(3)
115 return the color of a pixel.
116 gl_getpixelrgb(3)
117 store color components of a pixel.
118 gl_hline(3)
119 draw a horizontal line.
120 gl_line(3)
121 draw a line.
122 gl_circle(3)
123 draw a circle.
124 gl_fillbox(3)
125 fill a rectangular area.
126 Copying of screen buffers and page flipping
128 gl_copyscreen(3)
129 copy the screen contents of contexts.
130 gl_setscreenoffset(3)
131 set a memory offset for copyscreen.
132 gl_setdisplaystart(3)
133 set the start of the screen are displayed.
134 gl_enablepageflipping(3)
135 enables automatic page flipping.
136 Clipping
138 gl_disableclipping(3)
139 disables clipping.
140 gl_enableclipping(3)
141 enables clipping.
142 gl_setclippingwindow(3)
143 set the clipping window.
144 Text drawing primitives
146 gl_setfont(3)
147 set the text font to be used.
148 gl_setfontcolors(3)
149 set the font colors.
150 gl_expandfont(3)
151 expand a packed pixel font.
152 gl_colorfont(3)
153 change the color of a font.
154 gl_setwritemode(3)
155 set the font writemode flags.
156 gl_write(3), gl_writen(3)
157 write a text string.
158 gl_printf(3)
159 formatted output to the graphics screen.
160 gl_font8x8(3)
161 a packed 8x8 pixel font.
162 Pix- and Bitmap drawing
164 gl_getbox(3)
165 copy a rectangular pixmap from the screen to a buffer.
166 gl_copybox(3)
167 copy a rectangular screen area.
168 gl_copyboxfromcontext(3)
169 copy rectangular area from another context.
170 gl_copyboxtocontext(3)
171 copy a rectangular area to another context.
172 gl_putbox(3)
173 copy a pixmap to a rectangular area.
174 gl_putboxpart(3)
175 copy a partial pixmap to a rectangular area.
176 gl_putboxmask(3)
177 copy a masked pixmap to a rectangular area.
178 gl_putboxmaskcompiled(3)
179 copy a compiled masked pixmap to a rectangular area.
180 gl_compileboxmask(3)
181 compress a masked bitmap.
182 gl_compiledboxmasksize(3)
183 compute the size of a compiled masked box.
184 gl_scalebox(3)
185 scale a pixmap.
186 Palette handling
188 gl_getpalettecolor(3), gl_getpalettecolors(3), gl_getpalette(3)
189 read the color palette.
190 gl_setpalettecolor(3), gl_setpalettecolors(3), gl_setpalette(3)
191 set the color palette.
192 gl_setrgbpalette(3)
193 set a 256-color RGB palette.
194 Triangle primitives from threeDkit
196 gl_striangle(3)
197 draw a solid colored triangle.
198 gl_triangle(3)
199 draw a triangle with interpolated colors.
200 gl_swtriangle(3)
201 draw a solid pixmap mapped on a triangle.
202 gl_wtriangle(3)
203 draw a shadowed pixmap mapped on a triangle.
204 gl_trisetcolorlookup(3), gl_trigetcolorlookup(3)
205 manages a color lookup table for shadowing.
206 gl_trisetdrawpoint(3)
207 set a triangle drawing function.
208
210 WIDTH The width in pixels of the current graphics context.
211 HEIGHT Height in pixels.
213 BYTESPERPIXEL
215 Number of bytes per pixel (1, 2, 3 or 4).
216 BYTEWIDTH
218 Width of a scanline in bytes.
219 COLORS Number of colors.
221 BITSPERPIXEL
223 Number of significant color bits.
224 VBUF Address of the framebuffer.
226 __clip Clipping flag.
228 __clipx1
230 __clipy1
231 Top-left corner of clipping window.
232 __clipx2
234 __clipy2
235 Bottom-right corner of clipping window.
236
239 For three bytes per pixel (true color) modes, it is possible that pix‐
240 els cross a SVGA segment boundary. This should be correctly han‐
241 dled by most functions, but you never know. It can be avoided by
242 using a logical scanline length that is a divisor of 65536 (a power of
243 2), like 1024 (as opposed to 960) for 320x200 and 2048 (1920) for
244 640x480. For 800x600, this is impractical (4096 as opposed to 2400
245 doesn't fit in 2MB). Alternatively, avoid those functions by using a
246 virtual screen.
247
250 svgalib(7), libvga.config(5), testgl(6), threedkit(7), currentcon‐
251 text(3), gl_allocatecontext(3), gl_circle(3), gl_clearscreen(3),
252 gl_colorfont(3), gl_compileboxmask(3), gl_compiledboxmasksize(3),
253 gl_copybox(3), gl_copyboxfromcontext(3), gl_copyboxtocontext(3),
254 gl_copyscreen(3), gl_disableclipping(3), gl_enableclipping(3),
255 gl_enablepageflipping(3), gl_expandfont(3), gl_fillbox(3),
256 gl_font8x8(3), gl_freecontext(3), gl_getbox(3), gl_getcontext(3),
257 gl_getpalette(3), gl_getpalettecolor(3), gl_getpalettecolors(3),
258 gl_getpixel(3), gl_getpixelrgb(3), gl_hline(3), gl_line(3), gl_put‐
259 box(3), gl_putboxmask(3), gl_putboxmaskcompiled(3), gl_putboxpart(3),
260 gl_rgbcolor(3), gl_scalebox(3), gl_setclippingwindow(3), gl_setcon‐
261 text(3), gl_setcontextheight(3), gl_setcontextvga(3), gl_setcontextv‐
262 gavirtual(3), gl_setcontextvirtual(3), gl_setcontextwidth(3), gl_set‐
263 displaystart(3), gl_setfont(3), gl_setfontcolors(3), gl_setpalette(3),
264 gl_setpalettecolor(3), gl_setpalettecolors(3), gl_setpixel(3), gl_set‐
265 pixelrgb(3), gl_setrgbpalette(3), gl_setscreenoffset(3), gl_setwrite‐
266 mode(3), gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_triget‐
267 colorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3),
268 gl_write(3), gl_writen(3), gl_wtriangle(3).
269
272 There are many authors of svgalib. This page was edited by Michael
273 Weller <eowmob@exp-math.uni-essen.de>. The original documentation and
274 most of vgagl was done by Harm Hanemaayer <H.Hanemaayer@inter.nl.net>
275 though.
276Svgalib (>= 1.2.11) 2 Aug 1997 vgagl(7)