--- name: "X11::Protocol::Ext::XFree86_DGA" section: "3pm" platform: "linux" package: "perl-x11-protocol-other" version: "31-6" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/X11::Protocol::Ext::XFree86_DGA" --- # X11::Protocol::Ext::XFree86\_DGA(3pm) direct video memory access ## 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 \ ## 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 \.