NAME

       X11::Protocol::Ext::XFree86_DGA - direct video memory access

SYNOPSIS

        use X11::Protocol;
        my $X = X11::Protocol->new;
        $X->init_extension('XFree86-DGA')
          or print "XFree86-DGA extension not available";

DESCRIPTION

       The XFree86-DGA extension provides direct access to the video RAM of the server display.  A client
       program running on the same machine can use this to read or write directly instead of going through the X
       protocol.

       Accessing video memory will require some system-dependent trickery.  Under the Linux kernel for example
       video RAM is part of the /dev/mem physical address space and can be brought into program address space
       with an "mmap()" or accessed with "sysread()" and "syswrite()".  This normally requires root permissions.

       The requests offered here are only XFree86-DGA version 1.0 as yet and they don't say anything about the
       pixel layout etc in the memory -- that has to be divined separately.  (Version 2.0 has more for that.)

REQUESTS

       The following requests are made available with an "init_extension()", as per "EXTENSIONS" in
       X11::Protocol.

           my $ext_available = $X->init_extension('XFree86-DGA');

   XFree86-DGA 1.0
       "($server_major, $server_minor) = $X->XF86DGAQueryVersion()"
           Return the DGA protocol version implemented by the server.

       "$flags = $X->XF86DGAQueryDirectVideo ($screen_num)"
           Get flags describing direct video access on $screen_num (integer 0 upwards).  The only flag bit is

               0x0001   direct video available

           It's  possible to have the extension available but no direct video on a particular screen, or even on
           no  screens  at  all.   When   no   direct   video   the   requests   below   give   protocol   error
           "XF86DGANoDirectVideoMode".

       "($address, $width, $bank_size_bytes, $ram_size_kbytes) = $X->XF86DGAGetVideoLL ($screen_num)"
           Return the location and size of the video memory for $screen_num (integer 0 upwards).

           $address is a raw physical 32-bit address as an integer.  $width is in pixels.

           $bank_size_bytes  is  the  size  in  bytes accessible at a given time.  $ram_size_kbytes is the total
           memory in 1024  byte  blocks.   If  "$ram_size_kbytes*1024"  is  bigger  than  $bank_size_bytes  then
           "$X->XF86DGASetVidPage()" below must be used to switch among the banks to access all the RAM.

       "$X->XF86DGADirectVideo ($screen_num, $flags)"
           Enable or disable direct video access on $screen_num (integer 0 upwards).  $flags is bits

               0x0002    enable direct video graphics
               0x0004    enable mouse pointer reporting as relative
               0x0008    enable direct keyboard event reporting

           When direct video graphics is enabled (bit 0x0002) the server gives up control to the client program.

           If  the  graphics  card  doesn't  have  a  direct video mode then an "XF86DGANoDirectVideoMode" error
           results, or if the screen is not active (eg. switched away to  a  different  virtual  terminal)  then
           "XF86DGAScreenNotActive".

       "($width, $height) = $X->XF86DGAGetViewPortSize ($screen_num)"
           Get  the  size  of  the  viewport  on $screen_num (integer 0 upwards).  This is the part of the video
           memory actually visible on the monitor.  The memory might be bigger than the monitor.

       "$X->XF86DGASetViewPort ($screen_num, $x, $y)"
           Set the coordinates of the top-left corner of the visible part of the  video  memory  on  $screen_num
           (integer 0 upwards).

           This can be used when the video memory is bigger than the monitor to pan around that bigger area.  It
           can also be used for some double-buffering to display one part of memory while drawing to another.

       "$vidpage = $X->XF86DGAGetVidPage ($screen_num)"
       "$X->XF86DGASetVidPage ($screen_num, $vidpage)"
           Get  or  set  the  video  page  (bank)  on $screen_num (integer 0 upwards).  $vidpage is an integer 0
           upwards.

           This is used to access all the RAM when when the bank size is less than the total  memory  size  (per
           "XF86DGAGetVideoLL()" above).

       "$vidpage = $X->XF86DGAInstallColormap ($screen_num, $colormap)"
           Set the colormap on $screen_num to $colormap (integer XID).

           This  can  only  be used while direct video is enabled (per "XF86DGADirectVideo()" above) or an error
           "XF86DGAScreenNotActive" or "XF86DGADirectNotActivated" results.

       "$bool = $X->XF86DGAViewPortChanged ($screen_num, $num_pages)"
           Check whether a previous "XF86DGASetViewPort()" on $screen_num (integer  0  upwards)  has  completed,
           meaning a vertical retrace has occurred since that viewport location was set.

           This  is  used  for  double-buffering  (or  N-multi-buffering)  to check a viewport change has become
           visible.  $num_pages should be 2 for double-buffering and can be higher for multi-buffering.

SEE ALSO

       X11::Protocol

       /usr/share/doc/xserver-xfree86/README.DGA.gz

HOME PAGE

       <http://user42.tuxfamily.org/x11-protocol-other/index.html>

LICENSE

       Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde

       X11-Protocol-Other is free software; you can redistribute it and/or modify it under the terms of the  GNU
       General  Public  License  as  published  by  the  Free Software Foundation; either version 3, or (at your
       option) any later version.

       X11-Protocol-Other is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without
       even  the  implied  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
       Public License for more details.

       You should have received a copy of the GNU General Public License along with X11-Protocol-Other.  If not,
       see <http://www.gnu.org/licenses/>.

perl v5.28.1                                       2019-08-26               X11::Protocol::Ext::XFree86_DGA(3pm)