Provided by: libsvga1-dev_1.4.3-31_amd64 bug

NAME

       vga_accel - calls the graphics accelerator

SYNOPSIS

       #include <vga.h>

       int vga_accel(unsigned operation, ...);

DESCRIPTION

       This  is the major function of the new accelerator interface which was sketched in version
       1.2.3 (Michael: Hmm, it must have been later) but was implemented much later.

       The main goal is to define functions that  can  be  used  as  part  of  certain  kinds  of
       interesting  graphical  operations  (not necessarily interesting primitives on their own).
       Obvious useful primitives in their  own  are  FillBox,  ScreenCopy,  DrawHLineList  (solid
       polygon), DrawLine.

       An interesting purpose is the fast drawing of color bitmaps, both straight and transparent
       (masked, certain color not written). For masked bitmaps ("sprites"), there is a number  of
       possible  methods,  the availability of which depends on the chips. Caching in non-visible
       video memory is often useful. One way is to use a transparency color compare feature of  a
       BITBLT  chip,  either transferring the image from system memory or cached in video memory.
       If transparency compare is not available, it may be possible to first  clear  (zeroe)  the
       mask  in  the  destination area, and then use BITBLT raster-operation to OR the image into
       the destination (this requires the mask color to be 0). A higher level (library) interface
       should control this kind of operation.

       vga.h  contains  several  macros  which  may  be  used for operation.  Most of them accept
       several optional arguments which you may specify after them.  The  accel(6)  svgalib  demo
       shows  basic  usage  of  this  function.  The  function returns -1 if the operation is not
       available and 0 if it is (or better: wasi and could be performed).

       Currently the following parameters for vga_accel() are defined:

       vga_accel(ACCEL_FILLBOX, int x, int y, int w, int h)
              Simple solid fill of a box at pixels x, y with width w and height h in the  current
              foreground color

       vga_accel(ACCEL_SCREENCOPY, int x1, int y1, int x2, int y2, int w, int h)
              Simple  screen-to-screen  blit. It copies a box of width w and height h pixels from
              position x1, y1 to position x2, y2.  You may assume that the copy is non corrupting
              in case of overlapping source and destination areas.

       vga_accel(ACCEL_SCREENCOPYMONO, int x1, int y1, int x2, int y2, int w, int h)
              Monochrome  screen-to-screen  blit.  It copies a box of width w and height h pixels
              from position x1, y1 to position x2, y2.

              However, each pixel will all bits set to 0 is drawn in the background  color,  each
              pixel  with  all  bits  set  to  1  is drawn in the foreground color. To allow many
              different architectures supporting this routine, behaviour is undefined  for  other
              values. Bitmap transparency might be supported as well.

              You  should  not  expect  ACCEL_SCREENCOPYBITMAP  handling overlapping screen areas
              gracefully.

       vga_accel(ACCEL_PUTIMAGE, int x, int y, int w, int h, void *p)
              Straight image transfer. It fills the given box with the data  in  memory  area  p.
              The memory buffer must contain the pixels in the same representation as used in the
              vga memory, starting at the top left corner, from left to right, and then, line  by
              line, from up to down, without any gaps and interline spaces.

       vga_accel(ACCEL_DRAWLINE, int x1, int y1, int x2, int y2))
              General  line  draw.  Draws a line from x1, y1 to position x2, y2 in the foreground
              color.  You should not expect the reverse line from x2, y2 to position  x1,  y1  to
              use  the  exact same pixels on the screen.  Several, esp. hardware, algorithms tend
              to yield to surprising results.

       vga_accel(ACCEL_SETFGCOLOR, int color)
              Sets foreground color. It is used by most other draw commands.

       vga_accel(ACCEL_SETBGCOLOR, int color)
              Set background color. It is used by draw commands which might also

       vga_accel(ACCEL_SETTRANSPARENCY, int mode, ...)
              Set transparency mode, see the table below for an explanation parameters.

       vga_accel(ACCEL_SETRASTEROP, int mode)
              Set raster-operation, see the table below for an explanation of parameters.

       vga_accel(ACCEL_PUTBITMAP, int x, int y, int w, int h, void *p)
              Color-expand bitmap. This works similar to ACCEL_PUTIMAGE but the bitmap  *p  is  a
              one  bit  bitmap.  Each pixel related to a set bit in *p is drawn in the foreground
              color, the other pixels are drawn in the background color.

              Each byte at *p contains 8 pixels.  The lowest order bit of each byte  is  leftmost
              on the screen (contrary to the VGA tradition), irrespective of the bitmap bit order
              flag. Each scanline is aligned to a multiple of 32-bits.

              If the transparency mode is enabled (irrespective of the transparency color),  then
              bits  that  are  zero  in  the  bitmap are not written (the background color is not
              used).

       vga_accel(ACCEL_SCREENCOPYBITMAP, int x1, int y1, int x2, int y2, int w, int h)
              Color-expand from screen. This works similar to ACCEL_PUTBITMAP but the bitmap lies
              at position x1, y1 and the destination box at x2, y2.

              Alas, the sizes of the pixels in both bitmap are different. The bitmap *p must have
              the format corresponding to ACCEL_PUTBITMAP but will start  at  the  screen  memory
              location where the pixel (x1, y1) would be (probably in off screen memory).

              In  modes  where pixel will not start at byte boundaries (typically those with less
              then 256 colors), the pixel (x1, y1) must start at a byte boundary (for example  in
              a 16 color mode (4bpp rather than 8bpp for 256 colors) this means that x1 should be
              an even number).

              The easiest way to achieve this is probably to choose x1 == 0 in these situations.

              You should not expect  ACCEL_SCREENCOPYBITMAP  handling  overlapping  screen  areas
              gracefully.

       vga_accel(ACCEL_DRAWHLINELIST, int y, int n, int *x1, int *x2)
              Draw  horizontal  spans.  Each  of  the  *x1 and *x2 arrays contains n x-coordinate
              pairs. Starting with a horizontal line from *x1,y to *x2,y  consecutive  horizontal
              lines  (with  increasing  y values) are drawn using the start and end points in *x1
              and *x2.  This is usually a very quick  operation  and  useful  to  draw  arbitrary
              polygons (when the accelerator cannot do an arbitrary polygon fill itself).

       vga_accel(ACCEL_POLYLINE, int flag, int n, unsigned short *coords)
              draws a contiguous line through the n points listed in *coords.  *coords contains n
              pairs of shorts, the first is the x coordinate, the second is the y coordinate.

              Normally flag should have the value  ACCEL_START  |  ACCEL_END.   However,  if  the
              evaluation  of  the  points is costly, you can mix calculations and drawings.  Your
              first call to vga_accel(ACCEL_POLYLINE, ...)  must have ACCEL_START set. This  will
              initialize  the accelerator. If you do not specify ACCEL_END, you can (actually you
              have to) follow your call with another vga_accel(ACCEL_POLYLINE, ...)   call  which
              will give additional points to connect.

              It  is  important  that  no  other  operations  (even no color settings) take place
              between a call with ACCEL_START and  the  one  with  the  corresponding  ACCEL_END.
              Because  of this, it is also important that you lock the console with vga_lockvc(3)
              and vga_unlockvc(3), s.t. you cannot be interrupted by a console switch.

              It is allowed not to set ACCEL_END for your last call to  vga_accel(ACCEL_POLYLINE,
              ...).Thiswillnotdrawthelastpixelofthelast  line  which is important for some raster
              operations when  drawing  closed  polygons.   The  accelerator  will  automatically
              deinitialize when called with another operation in this situation.

              It  is  undefined what happens when you specify other values for flag and when your
              polyline contains only a single point. The line segments must also not be of length
              zero.

              For  implementors:  In  conjunction with raster operations (ROP_XOR, ROP_INV) it is
              important that endpoints of inner line section are only drawn once. If  you  cannot
              achieve that, you must signal that this function cannot be used in conjunction with
              raster operations.  In this case it is valid to always draw all points of the  line
              segments  including  the  endpoints  regardless  of  the  existence  of a ACCEL_END
              parameter.

       vga_accel(ACCEL_POLYHLINE, int flag, int y, int n, unsigned short *xcoords)
              This function combines the  features  of  ACCEL_POLYLINE  and  ACCEL_DRAWHLINELIST.
              Starting  in  row  y  horizontal  lines  are  drawn  from  top  to bottom. For each
              horizontal scanline the *coords array will contain a  number  m  followed  by  m  x
              coordinates  in  left  to right order. Horizontal lines are drawn between the first
              and the second, the third and the fourth  x  coordinates,  and  so  on.  If  the  m
              coordinates  are exhausted, y is increased, a new number m is read from the *coords
              array and operation continues.

              This procedure is done for n scan lines.

              In addition there is a flag parameter which works similar to ACCEL_POLYLINE.   Your
              first  call  to  ACCEL_DRAWHLINELIST  must  have the ACCEL_START bit set for proper
              initialization. The y parameter is ignored when ACCEL_START is not given.

              On contrary to ACCEL_POLYLINE it is required that the last call has  the  ACCEL_END
              bit set.

              The  function  is  intended  for  drawing  complex filled polygons using horizontal
              scanlines.  By issuing small and fast calls for few scanlines only it  is  possible
              to intermix drawing and calculations.

              The  operation  of ACCEL_POLYHLINE is undefined if the x coordinates are not sorted
              from left to right or there are zero length segments in any scan line or  if  n  or
              one of the m counters are zero, or one of the m's is not even.

       vga_accel(ACCEL_POLYFILLMODE, onoff)
              Switches polygon fill mode on (onoff non-zero) or off.

              When  in  polygon  fill  mode,  ACCEL_DRAWLINE  and ACCEL_POLYLINE will only draw a
              single point on each scanline of  each  line  segment.   ACCEL_SCREENCOPYMONO  will
              horizontally  scan  it's source area and start drawing in the foreground color when
              it encounters a set pixel. When the next pixel is encountered, it will start  using
              the background color and so on.

              This can be used for hardware filled polygons:

              1.     Enable polygon fill mode.

              2.     Fill  an  offscreen  rectangular  area  with  a the color with all bits zero
                     (usually black).

              3.     Draw a (usually closed) polygon outline in this offscreen area in the  color
                     with  all  bits  set  (usually  white).  To  get the proper bits set for the
                     polygon outline, it is recommended to use ROP_XOR s.t. outlines intersecting
                     in  a single point are handled correctly. To ensure that polygon corners are
                     handled right, both start and end points must be drawn  (in  ROP_XOR  mode).
                     Thus  it  is best to use ACCEL_DRAWLINE instead of ACCEL_POLYLINE.  Finally,
                     skip    drawing    all    horizontal    lines    (which    would     confuse
                     ACCEL_SCREENCOPYMONO).

              4.     Set  fore-  and  background colors, raster operation, bitmap transparency to
                     those you want for your polygon.

              5.     Use ACCEL_SCREENCOPYMONO to copy the offscreen pattern to the screen.

              The rasteroperations and transparency which  are  signalled  to  be  supported  for
              ACCEL_POLYFILLMODE  by  vga_ext_set(3)  are  actually  meant  to  apply to the last
              ACCEL_SCREENCOPYMONO call.

              Because this polygon drawing uses more screen read/write operations it is  probably
              slower  than  using  ACCEL_DRAWHLINELIST  or  ACCEL_POLYHLINE for drawing a polygon
              scanline by scanline. However, it is easier to use and it will work mostly  without
              intervention of the CPU which can do other calculations then. See BUGS below.

              It  is  unspecified if the left or right end points of the scanlines are drawn, and
              most probably some cards (like Mach32) will omit them on one end, at least. Because
              of  that  you  should  always  draw the boundary line in the fill color (or another
              color) after filling the polygon.

       vga_accel(ACCEL_SETMODE, mode)
              Set  blit  strategy.  There  are  two  choices  for  mode,  namely  BLITS_SYNC  and
              BLITS_IN_BACKGROUND.   The  first ensures that a vga_accel() call only returns when
              the accelerator has finished its operation. The  second  allows  for  an  immediate
              return  and  thus  allows  parallel  operation  of  the  CPU  and  the accelerator.
              Consecutive accelerator operations will wait for each other to complete (and  block
              if  necessary).  However, direct screen memory access (also when done implicitly by
              some call to an svgalib function) may find any intermediate state in vga memory  or
              even corrupt the running accelerator operation.

       vga_accel(ACCEL_SYNC)
              Wait for accelerator to finish when in vga_accel(BLITS_IN_BACKGROUND) mode.

       vga_accel(ACCEL_SETOFFSET, int address)
              set  a screen offset as vga_setdisplaystart(3) does. The same restrictions for this
              function as reported by vga_getmodeinfo(3) apply to address.

              Whenever the video screen offset is modified, the accelerator's offset will follow.
              However you can modify it later with this function.

       The following mode values are defined for vga_accel(ACCEL_SETTRANSPARENCY, int mode, ...)

       vga_accel(ACCEL_SETTRANSPARENCY, ENABLE_TRANSPARENCY_COLOR, int color)
              Whenever  one  of  the vga_accel() operations would draw a pixel in color color, no
              operation is performed and the destination pixel is left unchanged.  In  fact  that
              color is defined to be transparent.

       vga_accel(ACCEL_SETTRANSPARENCY, DISABLE_TRANSPARENCY_COLOR)
              disables the previous functionality.

       vga_accel(ACCEL_SETTRANSPARENCY, ENABLE_BITMAP_TRANSPARENCY)
              in  the  bitmap  expanding  operations  ACCEL_PUTBITMAP  and ACCEL_SCREENCOPYBITMAP
              whenever a non set bit is encountered, to not perform any  draw  operation.  The  0
              bits  do  not  draw  in  the  background  color.  Instead  they  are  defined to be
              transparent.

       vga_accel(ACCEL_SETTRANSPARENCY, DISABLE_BITMAP_TRANSPARENCY)
              disables the previous functionality.

       The following mode values are defined for vga_accel(ACCEL_SETRASTEROP, int mode)

       vga_accel(ACCEL_SETRASTEROP, ROP_COPY)
              Straight copy. Pixels drawn by vga_accel() replace the destination.

       vga_accel(ACCEL_SETRASTEROP, ROP_OR)
              Logical or.  Pixels  drawn  by  vga_accel()  are  logical  (bitwise)  ored  to  the
              destination.

       vga_accel(ACCEL_SETRASTEROP, ROP_AND)
              Logical  and.  Pixels  drawn  by  vga_accel()  are  logical  (bitwise) anded to the
              destination.

       vga_accel(ACCEL_SETRASTEROP, ROP_XOR)
              Logical exclusive or. Pixels drawn by vga_accel() are logical  (bitwise)  exclusive
              ored  to  the  destination  (bits  set  in  the drawn pixels flip those pits in the
              destination).

       vga_accel(ACCEL_SETRASTEROP, ROP_INV)
              Inversion. Pixels drawn by vga_accel()  are  inverted.  Which  color  is  drawn  is
              actually ignored. Any pixel which would be overwritten is simply inverted (bitwise)
              instead.

       IMPORTANT!  Please note that a 0 returned by  vga_accel(ACCEL_SETTRANSPARENCY,  int  mode,
       ...)   and  vga_accel(ACCEL_SETRASTEROP,  int  mode) simply means that the set function is
       available (and thus probably some of above features) but only partial functionality may be
       available.  The VGA_AVAIL_ROPMODES and VGA_AVAIL_TRANSMODES subfunctions of vga_ext_set(3)
       allow you to check for valid  parameters.  The  VGA_AVAIL_ROP  and  VGA_AVAIL_TRANSPARENCY
       subfunctions  return  which of the vga_accel operations are actually affected by these set
       functions.

       Instead of calling vga_accel() for each operation to find out if it is supported, you  can
       call:

       #include <vga.h>

       int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_ACCEL)

       When the logical bitwise and of the return value with one of the following predefined (one
       bit set only) integer constants is non zero, the  corresponding  operation  is  available:
       ACCELFLAG_FILLBOX,     ACCELFLAG_SCREENCOPY,    ACCELFLAG_PUTIMAGE,    ACCELFLAG_DRAWLINE,
       ACCELFLAG_SETFGCOLOR,           ACCELFLAG_SETBGCOLOR,           ACCELFLAG_SETTRANSPARENCY,
       ACCELFLAG_SETRASTEROP,           ACCELFLAG_PUTBITMAP,          ACCELFLAG_SCREENCOPYBITMAP,
       ACCELFLAG_DRAWHLINELIST, ACCELFLAG_SETMODE and ACCELFLAG_SYNC.

       In addition, calling

       #include <vga.h>

       int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_TRANSPARENCY)

       or

       int vga_ext_set(VGA_EXT_AVAILABLE, VGA_AVAIL_ROP)

       does not list the supported values for raster  operations  and  transparency  but  instead
       returns  the  ACCELFLAG_  values  for  the accelerator operations which respond the raster
       operation resp. transparency settings.

       The availability of the operations will usually depend on the current video mode selected.
       You  should  not try to use them or check for availability prior to selecting the mode you
       want to use with set_mode(3).

BUGS

       I found the Mach32 buggy in that it occasionally omits drawing last pixels of  lines  when
       in  polygon  fill  modes  (that  means,  a single point for the last scanline touched by a
       line).  Obviously this confuses the polygon fill hardware. However, screen corruption will
       always  be  restricted to a small area as ACCEL_SCREENCOPYMONO will work only on a limited
       area. It is not clear if this is a driver error, but it seems to be a hardware bug, and  I
       don't  know  a  clutch  to  avoid  it  yet.  In  case you experience problems with certain
       applications, try blit nopolyfillmode in the  configuration  file  or  the  SVGALIB_CONFIG
       environment variable.

       You  must  ensure that the given screen coordinates lie in screen memory. Actually you may
       not really be sure how offscreen areas  are  handled,  you  can  only  really  trust  that
       coordinates  which  are  visible  are  supported.  For  example,  the Mach32 restricts the
       allowable x and y coordinates to the range -512 .. 1535. However, even on a 1MB VGA memory
       card,  the offscreen point (0, 1599) would identify a valid screen memory location (if you
       could use it).

       Where supported, the vga_accel(ACCEL_SETOFFSET, ...)  directive might help to ease  things
       a bit in such situations.

       Svgalib's  accelerator  support  is  a  mess.  Right  now,  only  the Ark, the Cirrus, the
       Chips&Technologies, and the Mach32 svga drivers really support this function.  The  Mach32
       still  also  supports  the old style accelerator functions vga_bitblt(3), vga_blitwait(3),
       vga_fillblt(3), vga_hlinelistblt(3) and vga_imageblt(3) which were first designed for  the
       Cirrus  cards  and  thus the Mach32 has its problems emulating them. The gl_ functions use
       the accelerator to some extend.  Currently  the  use  both  the  new  and  the  old  style
       accelerator. You should avoid mixing calls of the new and the old style kinds.

       These  functions  are  not  well  tested.  You  should expect weird bugs. In any case, the
       accelerator is of not much use in many typical svgalib applications. Best if you  are  not
       using them.

       BEWARE!   You should not use the graphics accelerator together with the background feature
       of vga_runinbackground(3).  However, you can try using vga_lockvc(3) to lock the vc  prior
       to using the accelerator.

       The  Mach32  driver  does  this  on  it's  own,  and  even  keeps the console locked while
       background accelerator functions are in progress. Other drivers might not be as graceful.

SEE ALSO

       svgalib(7),  vgagl(7),   libvga.config(5),   accel(6),   vga_bitblt(3),   vga_blitwait(3),
       vga_ext_set(3),  vga_fillblt(3), vga_getmodeinfo(3), vga_hlinelistblt(3), vga_imageblt(3),
       vga_runinbackground(3), vga_runinbackground_version(3)

AUTHOR

       This manual page was edited by Michael Weller  <eowmob@exp-math.uni-essen.de>.  The  exact
       source of the referenced function as well as of the original documentation is unknown.

       It  is  very  likely  that  both  are  at  least to some extent are due to Harm Hanemaayer
       <H.Hanemaayer@inter.nl.net>.

       Occasionally this might be wrong. I hereby asked to be excused by the original author  and
       will  happily  accept  any  additions  or corrections to this first version of the svgalib
       manual.