Provided by: libsvga1-dev_1.4.3-29_i386 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.