From 71b32a9f75bbbfd9875d114260f5d08b56faf196 Mon Sep 17 00:00:00 2001 From: David Heidelberg Date: Tue, 21 Jun 2022 00:35:09 +0200 Subject: [PATCH] docs: briefly document Gallium Nine MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Credits: Axel Davy, lorn10, Pavel Ondračka Closes: https://gitlab.freedesktop.org/mesa/mesa/-/issues/4937 Acked-by: Filip Gawin Acked-by: Pavel Ondračka Signed-off-by: David Heidelberg Part-of: --- docs/envvars.rst | 22 +++++++++ docs/gallium-nine.rst | 48 +++++++++++++++++++ docs/gallium/distro.rst | 11 +++-- docs/index.rst | 1 + src/gallium/frontends/nine/README | 77 ------------------------------- 5 files changed, 79 insertions(+), 80 deletions(-) create mode 100644 docs/gallium-nine.rst delete mode 100644 src/gallium/frontends/nine/README diff --git a/docs/envvars.rst b/docs/envvars.rst index 027952f1b3d..c2c38ac0b55 100644 --- a/docs/envvars.rst +++ b/docs/envvars.rst @@ -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 ------------------------------------- diff --git a/docs/gallium-nine.rst b/docs/gallium-nine.rst new file mode 100644 index 00000000000..53626d8684c --- /dev/null +++ b/docs/gallium-nine.rst @@ -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 `_. +`Gallium 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 `_ with ``winetricks galliumnine``. +Aside from Wine, Gallium Nine works well with `Box86 `_. +Can be used via `Zink `_ even on the `Vulkan API `_. + +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 `_. + +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 diff --git a/docs/gallium/distro.rst b/docs/gallium/distro.rst index 67272034c53..d36c1234b2b 100644 --- a/docs/gallium/distro.rst +++ b/docs/gallium/distro.rst @@ -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 ^^^^^ diff --git a/docs/index.rst b/docs/index.rst index 762a3eba51a..217afaf787d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,6 +75,7 @@ Linux, FreeBSD, and other operating systems. gpu-perf-tracing extensions application-issues + gallium-nine viewperf xlibdriver diff --git a/src/gallium/frontends/nine/README b/src/gallium/frontends/nine/README deleted file mode 100644 index 4f478de1d6c..00000000000 --- a/src/gallium/frontends/nine/README +++ /dev/null @@ -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!