1vga_accel(3) Svgalib User Manual vga_accel(3)
2
6 vga_accel - calls the graphics accelerator
7
9 #include <vga.h>
10 int vga_accel(unsigned operation, ...);
12
15 This is the major function of the new accelerator interface which was
16 sketched in version 1.2.3 (Michael: Hmm, it must have been later) but
17 was implemented much later.
18 The main goal is to define functions that can be used as part of cer‐
20 tain kinds of interesting graphical operations (not necessarily inter‐
21 esting primitives on their own). Obvious useful primitives in their own
22 are FillBox, ScreenCopy, DrawHLineList (solid polygon), DrawLine.
23 An interesting purpose is the fast drawing of color bitmaps, both
25 straight and transparent (masked, certain color not written). For
26 masked bitmaps ("sprites"), there is a number of possible methods, the
27 availability of which depends on the chips. Caching in non-visible
28 video memory is often useful. One way is to use a transparency color
29 compare feature of a BITBLT chip, either transferring the image from
30 system memory or cached in video memory. If transparency compare is
31 not available, it may be possible to first clear (zeroe) the mask in
32 the destination area, and then use BITBLT raster-operation to OR the
33 image into the destination (this requires the mask color to be 0). A
34 higher level (library) interface should control this kind of operation.
35 vga.h contains several macros which may be used for operation. Most of
37 them accept several optional arguments which you may specify after
38 them. The accel(6) svgalib demo shows basic usage of this function. The
39 function returns -1 if the operation is not available and 0 if it is
40 (or better: wasi and could be performed).
41 Currently the following parameters for vga_accel() are defined:
43 vga_accel(ACCEL_FILLBOX, int x, int y, int w, int h)
46 Simple solid fill of a box at pixels x, y with width w and
47 height h in the current foreground color
48 vga_accel(ACCEL_SCREENCOPY, int x1, int y1, int x2, int y2, int w, int
50 h)
51 Simple screen-to-screen blit. It copies a box of width w and
52 height h pixels from position x1, y1 to position x2, y2. You
53 may assume that the copy is non corrupting in case of overlap‐
54 ping source and destination areas.
55 vga_accel(ACCEL_SCREENCOPYMONO, int x1, int y1, int x2, int y2, int w,
57 int h)
58 Monochrome screen-to-screen blit. It copies a box of width w and
59 height h pixels from position x1, y1 to position x2, y2.
60 However, each pixel will all bits set to 0 is drawn in the back‐
62 ground color, each pixel with all bits set to 1 is drawn in the
63 foreground color. To allow many different architectures support‐
64 ing this routine, behaviour is undefined for other values. Bit‐
65 map transparency might be supported as well.
66 You should not expect ACCEL_SCREENCOPYBITMAP handling overlap‐
68 ping screen areas gracefully.
69 vga_accel(ACCEL_PUTIMAGE, int x, int y, int w, int h, void *p)
71 Straight image transfer. It fills the given box with the data in
72 memory area p. The memory buffer must contain the pixels in the
73 same representation as used in the vga memory, starting at the
74 top left corner, from left to right, and then, line by line,
75 from up to down, without any gaps and interline spaces.
76 vga_accel(ACCEL_DRAWLINE, int x1, int y1, int x2, int y2))
78 General line draw. Draws a line from x1, y1 to position x2, y2
79 in the foreground color. You should not expect the reverse line
80 from x2, y2 to position x1, y1 to use the exact same pixels on
81 the screen. Several, esp. hardware, algorithms tend to yield to
82 surprising results.
83 vga_accel(ACCEL_SETFGCOLOR, int color)
85 Sets foreground color. It is used by most other draw commands.
86 vga_accel(ACCEL_SETBGCOLOR, int color)
89 Set background color. It is used by draw commands which might
90 also
91 vga_accel(ACCEL_SETTRANSPARENCY, int mode, ...)
94 Set transparency mode, see the table below for an explanation
95 parameters.
96 vga_accel(ACCEL_SETRASTEROP, int mode)
99 Set raster-operation, see the table below for an explanation of
100 parameters.
101 vga_accel(ACCEL_PUTBITMAP, int x, int y, int w, int h, void *p)
104 Color-expand bitmap. This works similar to ACCEL_PUTIMAGE but
105 the bitmap *p is a one bit bitmap. Each pixel related to a set
106 bit in *p is drawn in the foreground color, the other pixels are
107 drawn in the background color.
108 Each byte at *p contains 8 pixels. The lowest order bit of each
110 byte is leftmost on the screen (contrary to the VGA tradition),
111 irrespective of the bitmap bit order flag. Each scanline is
112 aligned to a multiple of 32-bits.
113 If the transparency mode is enabled (irrespective of the trans‐
115 parency color), then bits that are zero in the bitmap are not
116 written (the background color is not used).
117 vga_accel(ACCEL_SCREENCOPYBITMAP, int x1, int y1, int x2, int y2, int
120 w, int h)
121 Color-expand from screen. This works similar to ACCEL_PUTBITMAP
122 but the bitmap lies at position x1, y1 and the destination box
123 at x2, y2.
124 Alas, the sizes of the pixels in both bitmap are different. The
126 bitmap *p must have the format corresponding to ACCEL_PUTBITMAP
127 but will start at the screen memory location where the pixel
128 (x1, y1) would be (probably in off screen memory).
129 In modes where pixel will not start at byte boundaries (typi‐
131 cally those with less then 256 colors), the pixel (x1, y1) must
132 start at a byte boundary (for example in a 16 color mode (4bpp
133 rather than 8bpp for 256 colors) this means that x1 should be an
134 even number).
135 The easiest way to achieve this is probably to choose x1 == 0 in
137 these situations.
138 You should not expect ACCEL_SCREENCOPYBITMAP handling overlap‐
140 ping screen areas gracefully.
141 vga_accel(ACCEL_DRAWHLINELIST, int y, int n, int *x1, int *x2)
143 Draw horizontal spans. Each of the *x1 and *x2 arrays contains n
144 x-coordinate pairs. Starting with a horizontal line from *x1,y
145 to *x2,y consecutive horizontal lines (with increasing y values)
146 are drawn using the start and end points in *x1 and *x2. This
147 is usually a very quick operation and useful to draw arbitrary
148 polygons (when the accelerator cannot do an arbitrary polygon
149 fill itself).
150 vga_accel(ACCEL_POLYLINE, int flag, int n, unsigned short *coords)
152 draws a contiguous line through the n points listed in *coords.
153 *coords contains n pairs of shorts, the first is the x coordi‐
154 nate, the second is the y coordinate.
155 Normally flag should have the value ACCEL_START | ACCEL_END.
157 However, if the evaluation of the points is costly, you can mix
158 calculations and drawings. Your first call to
159 vga_accel(ACCEL_POLYLINE, ...) must have ACCEL_START set. This
160 will initialize the accelerator. If you do not specify
161 ACCEL_END, you can (actually you have to) follow your call with
162 another vga_accel(ACCEL_POLYLINE, ...) call which will give
163 additional points to connect.
164 It is important that no other operations (even no color set‐
166 tings) take place between a call with ACCEL_START and the one
167 with the corresponding ACCEL_END. Because of this, it is also
168 important that you lock the console with vga_lockvc(3) and
169 vga_unlockvc(3), s.t. you cannot be interrupted by a console
170 switch.
171 It is allowed not to set ACCEL_END for your last call to
173 vga_accel(ACCEL_POLYLINE, ...).Thiswillnotdrawthelastpixelofthe‐
174 last line which is important for some raster operations when
175 drawing closed polygons. The accelerator will automatically
176 deinitialize when called with another operation in this situa‐
177 tion.
178 It is undefined what happens when you specify other values for
180 flag and when your polyline contains only a single point. The
181 line segments must also not be of length zero.
182 For implementors: In conjunction with raster operations
184 (ROP_XOR, ROP_INV) it is important that endpoints of inner line
185 section are only drawn once. If you cannot achieve that, you
186 must signal that this function cannot be used in conjunction
187 with raster operations. In this case it is valid to always draw
188 all points of the line segments including the endpoints regard‐
189 less of the existence of a ACCEL_END parameter.
190 vga_accel(ACCEL_POLYHLINE, int flag, int y, int n, unsigned short *xco‐
192 ords)
193 This function combines the features of ACCEL_POLYLINE and
194 ACCEL_DRAWHLINELIST. Starting in row y horizontal lines are
195 drawn from top to bottom. For each horizontal scanline the
196 *coords array will contain a number m followed by m x coordi‐
197 nates in left to right order. Horizontal lines are drawn between
198 the first and the second, the third and the fourth x coordi‐
199 nates, and so on. If the m coordinates are exhausted, y is
200 increased, a new number m is read from the *coords array and
201 operation continues.
202 This procedure is done for n scan lines.
204 In addition there is a flag parameter which works similar to
206 ACCEL_POLYLINE. Your first call to ACCEL_DRAWHLINELIST must
207 have the ACCEL_START bit set for proper initialization. The y
208 parameter is ignored when ACCEL_START is not given.
209 On contrary to ACCEL_POLYLINE it is required that the last call
211 has the ACCEL_END bit set.
212 The function is intended for drawing complex filled polygons
214 using horizontal scanlines. By issuing small and fast calls for
215 few scanlines only it is possible to intermix drawing and calcu‐
216 lations.
217 The operation of ACCEL_POLYHLINE is undefined if the x coordi‐
219 nates are not sorted from left to right or there are zero length
220 segments in any scan line or if n or one of the m counters are
221 zero, or one of the m's is not even.
222 vga_accel(ACCEL_POLYFILLMODE, onoff)
224 Switches polygon fill mode on (onoff non-zero) or off.
225 When in polygon fill mode, ACCEL_DRAWLINE and ACCEL_POLYLINE
227 will only draw a single point on each scanline of each line seg‐
228 ment. ACCEL_SCREENCOPYMONO will horizontally scan it's source
229 area and start drawing in the foreground color when it encoun‐
230 ters a set pixel. When the next pixel is encountered, it will
231 start using the background color and so on.
232 This can be used for hardware filled polygons:
234 1. Enable polygon fill mode.
236 2. Fill an offscreen rectangular area with a the color with
238 all bits zero (usually black).
239 3. Draw a (usually closed) polygon outline in this offscreen
241 area in the color with all bits set (usually white). To
242 get the proper bits set for the polygon outline, it is
243 recommended to use ROP_XOR s.t. outlines intersecting in
244 a single point are handled correctly. To ensure that
245 polygon corners are handled right, both start and end
246 points must be drawn (in ROP_XOR mode). Thus it is best
247 to use ACCEL_DRAWLINE instead of ACCEL_POLYLINE.
248 Finally, skip drawing all horizontal lines (which would
249 confuse ACCEL_SCREENCOPYMONO).
250 4. Set fore- and background colors, raster operation, bitmap
252 transparency to those you want for your polygon.
253 5. Use ACCEL_SCREENCOPYMONO to copy the offscreen pattern to
255 the screen.
256 The rasteroperations and transparency which are signalled to be
258 supported for ACCEL_POLYFILLMODE by vga_ext_set(3) are actually
259 meant to apply to the last ACCEL_SCREENCOPYMONO call.
260 Because this polygon drawing uses more screen read/write opera‐
262 tions it is probably slower than using ACCEL_DRAWHLINELIST or
263 ACCEL_POLYHLINE for drawing a polygon scanline by scanline. How‐
264 ever, it is easier to use and it will work mostly without inter‐
265 vention of the CPU which can do other calculations then. See
266 BUGS below.
267 It is unspecified if the left or right end points of the scan‐
269 lines are drawn, and most probably some cards (like Mach32) will
270 omit them on one end, at least. Because of that you should
271 always draw the boundary line in the fill color (or another
272 color) after filling the polygon.
273 vga_accel(ACCEL_SETMODE, mode)
275 Set blit strategy. There are two choices for mode, namely
276 BLITS_SYNC and BLITS_IN_BACKGROUND. The first ensures that a
277 vga_accel() call only returns when the accelerator has finished
278 its operation. The second allows for an immediate return and
279 thus allows parallel operation of the CPU and the accelerator.
280 Consecutive accelerator operations will wait for each other to
281 complete (and block if necessary). However, direct screen memory
282 access (also when done implicitly by some call to an svgalib
283 function) may find any intermediate state in vga memory or even
284 corrupt the running accelerator operation.
285 vga_accel(ACCEL_SYNC)
287 Wait for accelerator to finish when in vga_accel(BLITS_IN_BACK‐
288 GROUND) mode.
289 vga_accel(ACCEL_SETOFFSET, int address)
291 set a screen offset as vga_setdisplaystart[4m(3) does. The same
292 restrictions for this function as reported by vga_getmodeinfo[4m(3)
293 apply to address.
294 Whenever the video screen offset is modified, the accelerator's
296 offset will follow. However you can modify it later with this
297 function.
298 The following mode values are defined for vga_accel(ACCEL_SETTRANS‐
301 PARENCY, int mode, ...)
302 vga_accel(ACCEL_SETTRANSPARENCY, ENABLE_TRANSPARENCY_COLOR, int color)
304 Whenever one of the vga_accel() operations would draw a pixel in
305 color color, no operation is performed and the destination pixel
306 is left unchanged. In fact that color is defined to be transpar‐
307 ent.
308 vga_accel(ACCEL_SETTRANSPARENCY, DISABLE_TRANSPARENCY_COLOR)
310 disables the previous functionality.
311 vga_accel(ACCEL_SETTRANSPARENCY, ENABLE_BITMAP_TRANSPARENCY)
313 in the bitmap expanding operations ACCEL_PUTBITMAP and
314 ACCEL_SCREENCOPYBITMAP whenever a non set bit is encountered, to
315 not perform any draw operation. The 0 bits do not draw in the
316 background color. Instead they are defined to be transparent.
317 vga_accel(ACCEL_SETTRANSPARENCY, DISABLE_BITMAP_TRANSPARENCY)
319 disables the previous functionality.
320 The following mode values are defined for vga_accel(ACCEL_SETRASTEROP,
323 int mode)
324 vga_accel(ACCEL_SETRASTEROP, ROP_COPY)
326 Straight copy. Pixels drawn by vga_accel() replace the destina‐
327 tion.
328 vga_accel(ACCEL_SETRASTEROP, ROP_OR)
330 Logical or. Pixels drawn by vga_accel() are logical (bitwise)
331 ored to the destination.
332 vga_accel(ACCEL_SETRASTEROP, ROP_AND)
334 Logical and. Pixels drawn by vga_accel() are logical (bitwise)
335 anded to the destination.
336 vga_accel(ACCEL_SETRASTEROP, ROP_XOR)
338 Logical exclusive or. Pixels drawn by vga_accel() are logical
339 (bitwise) exclusive ored to the destination (bits set in the
340 drawn pixels flip those pits in the destination).
341 vga_accel(ACCEL_SETRASTEROP, ROP_INV)
343 Inversion. Pixels drawn by vga_accel() are inverted. Which color
344 is drawn is actually ignored. Any pixel which would be overwrit‐
345 ten is simply inverted (bitwise) instead.
346 IMPORTANT! Please note that a 0 returned by vga_accel(ACCEL_SETTRANS‐
349 PARENCY, int mode, ...) and vga_accel(ACCEL_SETRASTEROP, int mode)
350 simply means that the set function is available (and thus probably some
351 of above features) but only partial functionality may be available.
352 The VGA_AVAIL_ROPMODES and VGA_AVAIL_TRANSMODES subfunctions of
353 vga_ext_set(3) allow you to check for valid parameters. The
354 VGA_AVAIL_ROP and VGA_AVAIL_TRANSPARENCY subfunctions return which of
355 the vga_accel operations are actually affected by these set functions.
356 Instead of calling vga_accel() for each operation to find out if it is
359 supported, you can call:
360 #include <vga.h>
362 int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_ACCEL)
364 When the logical bitwise and of the return value with one of the fol‐
366 lowing predefined (one bit set only) integer constants is non zero, the
367 corresponding operation is available: ACCELFLAG_FILLBOX,
368 ACCELFLAG_SCREENCOPY, ACCELFLAG_PUTIMAGE, ACCELFLAG_DRAWLINE,
369 ACCELFLAG_SETFGCOLOR, ACCELFLAG_SETBGCOLOR, ACCELFLAG_SETTRANSPARENCY,
370 ACCELFLAG_SETRASTEROP, ACCELFLAG_PUTBITMAP, ACCELFLAG_SCREENCOPYBITMAP,
371 ACCELFLAG_DRAWHLINELIST, ACCELFLAG_SETMODE and ACCELFLAG_SYNC.
372 In addition, calling
374 #include <vga.h>
376 int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_TRANSPARENCY)
378 or
380 int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_ROP)
382 does not list the supported values for raster operations and trans‐
384 parency but instead returns the ACCELFLAG_ values for the accelerator
385 operations which respond the raster operation resp. transparency set‐
386 tings.
387 The availability of the operations will usually depend on the current
390 video mode selected. You should not try to use them or check for
391 availability prior to selecting the mode you want to use with
392 set_mode(3).
393
395 I found the Mach32 buggy in that it occasionally omits drawing last
396 pixels of lines when in polygon fill modes (that means, a single point
397 for the last scanline touched by a line). Obviously this confuses the
398 polygon fill hardware. However, screen corruption will always be
399 restricted to a small area as ACCEL_SCREENCOPYMONO will work only on a
400 limited area. It is not clear if this is a driver error, but it seems
401 to be a hardware bug, and I don't know a clutch to avoid it yet. In
402 case you experience problems with certain applications, try blit
403 nopolyfillmode in the configuration file or the SVGALIB_CONFIG environ‐
404 ment variable.
405 You must ensure that the given screen coordinates lie in screen memory.
407 Actually you may not really be sure how offscreen areas are handled,
408 you can only really trust that coordinates which are visible are sup‐
409 ported. For example, the Mach32 restricts the allowable x and y coordi‐
410 nates to the range -512 .. 1535. However, even on a 1MB VGA memory
411 card, the offscreen point (0, 1599) would identify a valid screen mem‐
412 ory location (if you could use it).
413 Where supported, the vga_accel(ACCEL_SETOFFSET, ...) directive might
415 help to ease things a bit in such situations.
416 Svgalib's accelerator support is a mess. Right now, only the Ark, the
418 Cirrus, the Chips&Technologies, and the Mach32 svga drivers really sup‐
419 port this function. The Mach32 still also supports the old style accel‐
420 erator functions vga_bitblt(3), vga_blitwait(3), vga_fillblt(3),
421 vga_hlinelistblt(3) and vga_imageblt(3) which were first designed for
422 the Cirrus cards and thus the Mach32 has its problems emulating them.
423 The gl_ functions use the accelerator to some extend. Currently the use
424 both the new and the old style accelerator. You should avoid mixing
425 calls of the new and the old style kinds.
426 These functions are not well tested. You should expect weird bugs. In
428 any case, the accelerator is of not much use in many typical svgalib
429 applications. Best if you are not using them.
430 BEWARE! You should not use the graphics accelerator together with the
432 background feature of vga_runinbackground(3). However, you can try
433 using vga_lockvc(3) to lock the vc prior to using the accelerator.
434 The Mach32 driver does this on it's own, and even keeps the console
436 locked while background accelerator functions are in progress. Other
437 drivers might not be as graceful.
438
441 svgalib(7), vgagl(7), libvga.config(5), accel(6), vga_bitblt(3),
442 vga_blitwait(3), vga_ext_set(3), vga_fillblt(3), vga_getmodeinfo(3),
443 vga_hlinelistblt(3), vga_imageblt(3), vga_runinbackground(3), vga_run‐
444 inbackground_version(3)
445
447 This manual page was edited by Michael Weller <eowmob@exp-math.uni-
448 essen.de>. The exact source of the referenced function as well as of
449 the original documentation is unknown.
450 It is very likely that both are at least to some extent are due to Harm
452 Hanemaayer <H.Hanemaayer@inter.nl.net>.
453 Occasionally this might be wrong. I hereby asked to be excused by the
455 original author and will happily accept any additions or corrections to
456 this first version of the svgalib manual.
457Svgalib (>= 1.2.11) 27 July 1997 vga_accel(3)