docs: briefly document Gallium Nine
Credits: Axel Davy, lorn10, Pavel Ondračka Closes: https://gitlab.freedesktop.org/mesa/mesa/-/issues/4937 Acked-by: Filip Gawin <filip@gawin.net> Acked-by: Pavel Ondračka <pavel.ondracka@gmail.com> Signed-off-by: David Heidelberg <david.heidelberg@collabora.com> Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/17154>
This commit is contained in:
David Heidelberg
Marge Bot
parent
c08f51d0cf
commit
71b32a9f75
|
|
@ -532,6 +532,28 @@ Clover environment variables
|
|||
appended after the options set by the OpenCL program in
|
||||
``clLinkProgram``.
|
||||
|
||||
|
||||
Nine frontend environment variables
|
||||
-----------------------------------
|
||||
|
||||
:envvar:`D3D_ALWAYS_SOFTWARE`
|
||||
an integer, which forces Nine to use the CPU instead of GPU acceleration.
|
||||
|
||||
:envvar:`NINE_DEBUG`
|
||||
a comma-separated list of named flags that do debugging things.
|
||||
Use `NINE_DEBUG=help` to print a list of available options.
|
||||
|
||||
:envvar:`NINE_FF_DUMP`
|
||||
a boolean, which dumps shaders generated by a fixed function (FF).
|
||||
|
||||
:envvar:`NINE_SHADER`
|
||||
a comma-separated list of named flags, which do alternate shader handling.
|
||||
Use `NINE_SHADER=help` to print a list of available options.
|
||||
|
||||
:envvar:`NINE_QUIRKS`
|
||||
a comma-separated list of named flags that do various things.
|
||||
Use `NINE_DEBUG=help` to print a list of available options.
|
||||
|
||||
Softpipe driver environment variables
|
||||
-------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
Gallium Nine
|
||||
============
|
||||
|
||||
The Gallium frontend, which implements Direct3D 9.
|
||||
|
||||
Nine implements the full IDirect3DDevice9 COM interface and a custom COM interface called ID3DAdapter9, which is used to implement the final IDirect3D9Ex COM interface.
|
||||
ID3DAdapter9 is completely agnostic regarding the window system code, meaning this can be provided by wine, Xlib, Wayland, etc.
|
||||
|
||||
Gallium Nine is commonly used in conjunction with `Wine <https://www.winehq.org/>`_.
|
||||
`Gallium Nine Standalone <https://github.com/iXit/wine-nine-standalone>`_ is the standalone version of the Wine parts of Gallium Nine which makes it possible to use it with any stock Wine version. It's simple to install through `Winetricks <https://github.com/Winetricks/winetricks>`_ with ``winetricks galliumnine``.
|
||||
Aside from Wine, Gallium Nine works well with `Box86 <https://ptitseb.github.io/box86/>`_.
|
||||
Can be used via `Zink <https://www.supergoodcode.com/to-the-nines/>`_ even on the `Vulkan API <https://en.wikipedia.org/wiki/Vulkan>`_.
|
||||
|
||||
In the majority of cases this implementation has better performance than Wine doing the translation from D3D9 to OpenGL itself.
|
||||
|
||||
It's also possible to use D3D9 directly from the Linux environment. For tests, demos, and more details, you can see `this repository <https://github.com/iXit/nine-tests>`_.
|
||||
|
||||
Build
|
||||
-----
|
||||
|
||||
Beware: Most Direct3D games are 32-bit, and thus need a 32-bit version of Mesa.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ meson configure \
|
||||
-D gallium-nine=true \
|
||||
-D dri3=true \
|
||||
...
|
||||
|
||||
Paths
|
||||
-----
|
||||
|
||||
You need to point wine-nine-standalone to the location of ``d3dadapter9.so``.
|
||||
If you use distribution packaged Mesa, it should work out of the box.
|
||||
|
||||
There are three options (sorted from permanent to temporary):
|
||||
- compile Wine Nine Standalone with ``D3D9NINE_MODULEPATH`` pointing to your local library
|
||||
- set ModulePath of Software\Wine\Direct3DNine in the wine registers
|
||||
- ``$ D3D_MODULE_PATH="$MESA_INSTALLDIR/lib/d3d/d3dadapter9.so" wine ...``
|
||||
|
||||
Run
|
||||
---
|
||||
|
||||
Before running your application in Wine, verify that everything works as expected by running:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ wine ninewinecfg
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
Distribution
|
||||
============
|
||||
|
||||
Along with the interface definitions, the following drivers, gallium frontends,
|
||||
Along with the interface definitions, the following drivers, Gallium frontends,
|
||||
and auxiliary modules are shipped in the standard Gallium distribution.
|
||||
|
||||
Drivers
|
||||
|
|
@ -101,10 +101,15 @@ GLX
|
|||
MesaGL
|
||||
^^^^^^
|
||||
|
||||
The gallium frontend implementing a GL state machine. Not usable as
|
||||
a standalone frontend; Mesa should be built with another gallium frontend,
|
||||
The Gallium frontend implementing a GL state machine. Not usable as
|
||||
a standalone frontend; Mesa should be built with another Gallium frontend,
|
||||
such as :ref:`DRI` or EGL.
|
||||
|
||||
Nine
|
||||
^^^^
|
||||
|
||||
The Gallium frontend implements the Direct3D 9 API.
|
||||
|
||||
VDPAU
|
||||
^^^^^
|
||||
|
||||
|
|
|
|||
|
|
@ -75,6 +75,7 @@ Linux, FreeBSD, and other operating systems.
|
|||
gpu-perf-tracing
|
||||
extensions
|
||||
application-issues
|
||||
gallium-nine
|
||||
viewperf
|
||||
xlibdriver
|
||||
|
||||
|
|
|
|||
|
|
@ -1,77 +0,0 @@
|
|||
Quickstart Guide
|
||||
|
||||
*** Configure and build mesa
|
||||
CFLAGS="-m32" CXXFLAGS="-m32" ./autogen.sh --prefix=/usr \
|
||||
--with-gallium-drivers=nouveau,r600,swrast --enable-nine \
|
||||
--enable-debug --enable-texture-float --with-dri-drivers= --disable-dri \
|
||||
--disable-opengl --disable-egl --disable-vdpau --disable-xvmc --disable-gbm \
|
||||
--disable-llvm
|
||||
make
|
||||
|
||||
*** Then we create some symlinks to mesa:
|
||||
ln -s "`pwd`/lib/gallium/libd3dadapter9.so.0.0.0" /usr/lib/
|
||||
ln -s "`pwd`/lib/gallium/libd3dadapter9.so.0" /usr/lib/
|
||||
ln -s "`pwd`/lib/gallium/libd3dadapter9.so" /usr/lib/
|
||||
ln -s "`pwd`/include/d3dadapter" /usr/include/
|
||||
|
||||
*** Clone and build a patched wine
|
||||
git clone git@github.com:iXit/wine.git
|
||||
./configure
|
||||
make
|
||||
|
||||
*** And finally we create some symlinks to our patched wine files:
|
||||
for f in d3d9.dll gdi32.dll user32.dll wineps.drv winex11.drv;
|
||||
do
|
||||
mv /usr/lib/wine/$f.so /usr/lib/wine/$f.so.old
|
||||
ln -s "`pwd`/dlls/`basename -s .dll $f`/$f.so" /usr/lib/wine/
|
||||
done
|
||||
|
||||
*** Activating it within wine
|
||||
regedit
|
||||
Navigate to HKCU\Software\Wine\Direct3D
|
||||
If it's not there, create it
|
||||
Create a new DWORD value called UseNative
|
||||
Set its value to 1
|
||||
|
||||
Every Direct3D9 program will now try using nine before wined3d
|
||||
|
||||
If you want to selectively enable it per-exe instead, use the key:
|
||||
HKCU\Software\Wine\AppDefaults\app.exe\Direct3D\UseNative
|
||||
where app.exe is the name of your .exe file
|
||||
|
||||
|
||||
*** HOW IT WORKS ***
|
||||
|
||||
Nine implements the full IDirect3DDevice9 COM interface and a custom COM
|
||||
interface called ID3DAdapter9 which is used to implement a final IDirect3D9Ex
|
||||
COM interface.
|
||||
ID3DAdapter9 is completely devoid of window system code, meaning this can be
|
||||
provided by wine, Xlib, Wayland, etc. It's inadvisible to write a non-Windows
|
||||
backend though, as we don't want to encourage linux developers to use this API.
|
||||
|
||||
The gallium frontend is compiled, along with pipe-loader, into a library called
|
||||
libd3dadapter9.so. This library loads pipe_[driver].so drivers on demand and
|
||||
exports a single symbol for getting a subsystem driver. Currently only DRM is
|
||||
supported.
|
||||
This library is then linked to the library implementing the IDirect3D9[Ex]
|
||||
interface and the actual Direct3D9 entry points (Direct3DCreate9[Ex])
|
||||
|
||||
The implementation of IDirect3D9[Ex] lies within wine and coexists with
|
||||
wined3d. It's loaded on demand and so if it's not there, it doesn't have any
|
||||
drivers or something else is wrong, d3d9.dll will automatically revert to using
|
||||
wined3d.
|
||||
Whether or not it's even tried is determined by 2 DWORD registry keys.
|
||||
> HKCU\Software\Wine\Direct3D\UseNative
|
||||
> HKCU\Software\Wine\AppDefaults\app.exe\Direct3D\UseNative
|
||||
The former is the global on-switch. The latter is per-exe.
|
||||
|
||||
The driver search path can be set at configure time with
|
||||
--with-gallium-driver-dir and overridden at runtime with D3D9_DRIVERS_PATH.
|
||||
Debugging information can be gotten with the WINEDEBUG channels d3d9 and
|
||||
d3dadapter, and gallium frontend debug information can be gotten with NINE_DEBUG.
|
||||
Help on NINE_DEBUG is shown through NINE_DEBUG=help
|
||||
|
||||
Finally, the ID3DPresent[Group] and ID3DAdapter9 interfaces are not set in
|
||||
stone, so feel free to hack on those as well as st/nine.
|
||||
|
||||
Happy Hacking!
|
||||
Loading…
Reference in New Issue