## nVidia 3D add-on Alpha 4 with Mesa 3.4.2 README (R5 and Max)

This is the alpha 4 release of the nVidia 3D add-on driver including Mesa 3.4.2 library for BeOS R5, Dano, Zeta and Max edition. This driver requires 2D driver 0.74 in order to work (otherwise your system will hang). Make sure you let the 2D driver use it's default DMA mode for acceleration: it's preset in nv.settings. If you used the Alpha 1 3D add-on you need to update the nv.settings file as that one used PIO mode! Reboot after installing the 2D driver: only after a reboot will the new driver be in effect and can 3D applications be used successfully.

#### Status since Alpha 3.5:

- Alpha 4 uses Mesa 3.4.2 again. Alpha 4 contains numerous bugfixes compared to all older versions, and it remains at the speed of Alpha 3.5 (sometimes even better):
  - on a P4@2.8Ghz with NV18, GeForce4-MX440 the teapot now spins at 800fps using default settings;
  - on the same system Quake2 timedemo1 runs at 125fps in 640x480x16 fullscreen mode using default settings.
- The driver still only works on NV04 (TNT1) upto/including NV18 (GeForce 4 MX). Although I spent a lot of time to overcome this, that didn't happen yet.
- The driver is still slow compared to Windows and Linux closed-source drivers. This is partly because we're using such an old version of Mesa, and partly because of lacking info on enabling some nice features (like compressed Z-buffering).
- The driver still only supports one 3D app at a time, and only works 'completely' in 16- and 32bit desktops.
- Still, this driver outperforms the original UtahGLX driver a lot (both speed and quality wise), and gives us some interesting options on BeOS. So enjoy it if you can. :-)
- Added features (require reboots to take effect currently):
  - Force retrace synced swapbuffer execution: enable this option via the driver's nv.settings file option: force_sync true. This option is nice to use, it improves output quality considerably (removes tearing), although it slows the fps down;
  - Force GPU speed: enable and set this option via the driver's nv.settings file option: gpu_clk. The number is the clock frequency in Mhz. Personally, I wouldn't use this one though: it's dangerous if used incorrectly while currently not improving speed much;
  - Force RAM speed: enable and set this option via the driver's nv.settings file option: ram_clk. The number is the clock frequency in Mhz. Although I recommend not using this option either, it potentially speeds up rendering some more, since currently RAM access is the biggest bottleneck in the hardware for us. Still: dangerous option.
- Note please: the 'primary' nv.setting is not compatible with the 3D add-on currently. Therefore you shouldn't enable it when you want to use accelerated 3D.

I want to thank BeOS Mr.X explicitly for his help and extensive testing during development of Alpha 4. Without him this release would have contained a lot less bug-fixes. So, thanks Mr.X!!
(Mr. X is a real 'BeOS-based' hardcore gamer I'd say! :-)

#### Fixes for Alpha 4:

- Quake 2 now renders the gamescores, texts, firing-cross, etc. correctly: driver now calls _mesa_swapbuffers() to let Mesa finish all rendering before Swapbuffers() is executed;
- Quake 2's 'menu_playerconfig'/multiplayer setup (for example) was fixed by (re)enabling support for partly erasing color and Z-buffers;
- Fixed texture filtering: engine nolonger hangs while using GL_LINEAR_MIPMAP_LINEAR. The driver programmed the engine incorrectly when switching back from textured drawing to 'untextured' drawing (selecting the next higher filtering 'level' instead of selecting 'no filtering');
- Partly rendering lines and triangles (scissoring) was (re)enabled: this seems to fix rendering slowness during 'observe' mode in Quake 2 when you are outside of a map;
- The driver incorrectly programmed fog colorspaces into the engine (forgot a color-component). Now fixed;
- Fixed programming of openGL context colorspaces: the BGLview constructor in the software driver incorrectly used a 'zero-define' (BGL_RGB) to determine colorspace info. Also added modifying the context colorspace setting upon modeswitches. This fixes (among others) 'grabbing' the teapot;
- Removed old 'fake-bitmap' code: resized output is now 'in sync' trhoughout the driver. This (at least) fixes some rendering faults during software rendering mode (fault looked like lost h_sync on a analog TVset);
- Added extra wait_for_engine_idle function for all software interface routines accessing color- and Z-buffers. This makes grabbing the teapot work 'smooth' even in high-res modes (among others);
- Added 'workaround' for backface culling (Mesa internal roundoff!?!) errors. Now rendering triangles that are 'nearly' visible too. This fixes 'next room pixels shining trough walls error' on Quake2 (at least). Note that this was especially visible when you were in a room with a outside wall, if the outside view behind it was very bright (Enabling hardware culling also fixes the problem, but it's much slower than using software culling at this point!);
- The looper is now locked when LockGL() is called; but also when Swapbuffers() is executed. Note BTW that apps should call LockGL() before calling Swapbuffers(): Quake2 apparantly forgets this for the audio options in the menu system;
- Fixed Quake2 output left-top position offset in fullscreen mode after modeswitches (R5 exhibited this fault only). Driver now issues BWindow's Hide()/Show() explicitly upon BGLview's Show() events to keep Quake2 rendering in direct mode (previously it fell-back into indirect rendering mode). It seems BTW R5's Window Frame() function doesn't (always) return updated content;
- There might even be a few more fixes in the driver that I forgot about.

#### Fixes for Alpha 3:

- Locking/unlocking the engine is now done in the driver's RenderStart and RenderFinish hooks. This speeds up rendering a bit, while the 2D driver keeps on working as usual (on a P4@2.8Ghz with NV18, GeForce4-MX440 the teapot now spins at 700fps (upto 800fps with alpha 4) using default settings);
- The driver nolonger attempts to use NV20 and higher: instead it will segfault for now. Which is probably 'better' than making your system 'hang'.

Installing the 3D add-on is nothing more than moving or copying the two libraries libGL.so and libGLU.so into the ~/config/lib folder. For convenience, I added the 2D driver 0.74 including a correctly preset nv.settings file in the archive. Also included are precompiled demo applications.
If, while testing, you hang your system, you should hit ALT, CTRL and DEL simultaneously (and keep that pressed down for a few seconds) to reboot. If it turns out you cannot run the driver/library just delete the files libGL.so and libGLU.so from your ~/config/lib folder and you should be OK. Without even rebooting: as those libraries are only loaded while you run an app using it.
If you test this 3D add-on you are encouraged to provide feedback. Feedback will tell us best what the actual useability of this attempt is in the end, and where additional fixes are needed. Feedback can be sent by Email or by talkback on the BeBits entry that I have created for this 3D driver.
OK, below you'll find a table containing the status of the driver, followed by a table indicating the status of that driver for several applications. I hope it's all of use to you! Have fun...
Table: Driver version 'alpha 4' status.

### Item: | ### Status:
OpenGL | Version 1.2.
Accelerated libraries | libGL.so is accelerated and contains the 3D add-on driver. libGLU.so is a utility library that runs on top of libGL.so, it contains no internal acceleration. If libGLU accelerates, it does so by using libGL.
Engine access type | DMA mode. You want this. Believe me ;-)
Supported colordepths | 16 and 32 bit modes are fully working, 15 bit mode is partially working. 8 bit mode isn't implemented yet. At least 15 bit mode will be completed, but not before switching to Mesa 6.2.
Supported cards | NV04 (TNT 1) upto and including (the now fast performing) NV18 (GeForce 4MX). I'll try to get more modern cards up in the future. Currently the driver blocks use on NV20 and higher.
3D Rendering functions | Straight and AA (anti-aliased) point and line functions. Straight triangle function: Although Mesa 3.4.2 supports AA triangles, it isn't implemented in the driver yet: it will use non-AA instead. Support for AA triangles will be setup later if possible (engine command is known), after we switch to Mesa 6.2.1. The Depth (Z) buffer is fixed at 16 bit depth.
3D Texturing | Single texturing is supported. Multiple texturing will be setup later if possible (engine command is known). Texture filtering is supported (bilinear, trilinear).
3D States | Line and Polygon stippling is not supported (driver falls back to software rendering mode so it renders OK but is slow); Stencil buffering is not supported (driver falls back to software rendering mode); Drawing into the frontbuffer is not yet supported (driver does that using software rendering: works but is slow); Single buffering is not yet supported (driver forces doublebuffering in BGLView constructor).
3D driver's 2D Functions | Swapbuffers() is accelerated for both BWindow (non-direct) and BDirectWindow (direct) modes; Triple buffering could be setup later on (Be's libraries do that? Or do they 'just' 'fallback' to the backbuffer as source for intermediate frontbuffer updates like Mesa 6.2.1 does?). Triple buffering could probably be an easy fix for 'single buffered' contexts (which will actually be double buffered then), and it helps out for slow rendering apps when you move their windows off- and then onscreen again. The Alpha 2 driver copies the backbuffer to front in such a case just like Mesa 6.2.1 does. The downside is that you might see a partially rendered advance copy of the 'new' backbuffer during a short time. Anyway: much better than no update at all ;-) Non-direct BWindow mode will not work correctly even when we use BGLView's Invalidate() and Draw() functions for 'back' to front rendering instead of doing that in Swapbuffers() (confirmed by testing now). We really need to loose support for Non-direct mode!; Swapbuffers() uses 2D blits, even for fullscreen. Literal swapping for fullscreen apps might be setup later (engine commands are known), although engine lockups currently happen in non-retrace-synced modes (confirmed by testing). Speed gain possible is not much currently: upto some 5% in 1024x768x32 mode: tested with Alpha 4); In direct BDirectWindow mode the DirectConnected() clipping_info turns out to be working after all! (apart from the BMenuBar error for which I have a workaround in place). This means you can drag direct windows like a madman, without errors appearing onscreen ;-) In non-direct BWindow mode drawing errors will be made of you move the application window to fast, or if you move other windows over the application window to fast. This cannot be fixed. Period. Scaling is supported now: When your app calls glViewPort() on resize events the context will be resized accordingly. If you don't call glViewPort() you will see repeating patterns or rubbish in the extra 'room' (when sizing up), or you will see only part of the applications output (sizing down). Could be fixed for direct mode in a future release (showing whitespace on upscaling).
BView's function activation | Be's flags B_WILL_DRAW, B_PULSE_NEEDED and B_FRAME_EVENTS are required for BGLView: some applications rely on it without explicitly issuing them. These flags are hardcoded added by the driver when an application creates a BGLView. Driver stability for B_FRAME_EVENTS and the like is guaranteed by it calling LockLooper()/UnlockLooper() inside the LockGL()/UnlockGL() hooks. Make sure your app calls LockGL()/UnlockGL() for all drawing commands, including openGL calls. Also make sure the context stays locked for the shortest amount of time possible, to maintain least latency for system events that might happen asynchronously to rendering (i.e. keyboard/mouse lagging!).

Table: Driver version 'alpha 4' status.
Table: Status for tested applications.

### App name: | ### Location: | ### Status: | ### Mode: | ### Faults: | ### Driver or library failsafe:
3Dlife | Optional sample code | Working as is | BWindow/non-direct mode | Doesn't call glViewport() | Driver calls glViewport() while servicing a backbuffer clear command when it detects no backbuffer was created before. glViewport() takes care of creation among other things.
GLteapot | Optional sample code | Working after relinking | BDirectWindow/direct mode | None | Relinking against both libGL.so and libGLU.so is required because some items used are in libGL.so these days, while being in libGLU.so at Mesa 3.4.2 'time'. We are 'going back in time'. Fully operational now: resizing and grabbing works.
Demo | Mesa 3.4.2 | Working after fix | BWindow/non-direct mode | Doesn't call glPopMatrix() | Added glPopMatrix() to the application. A library failsafe can be done in theory, but it requires additional code. It would need to check if the stack still contains a Matrix when Swapbuffers() is called (or so). Checking would be state-dependant. Resizing works.
Sample | Mesa 3.4.2, BeBook: openGL kit, BGLView | Working as is, including resizing. | BWindow/non-direct mode | None | None
GLQuake for BeOS R4.5 running on R5/dano | http://www.aixplosive.de/projects.html | Working after fixing keyboard lockups (minizing context-locked time and/or rewriting keyboard/mouse handling) | BDirectWindow/direct mode | Fixed keyboard/mouse handling inside game engine. | This application works OK now: 'timerefresh' by default renders in the frontbuffer: that's slow as it's software rendered, so I modified it to work in the backbuffer; The lockups caused by touching the keyboard were fixed by keeping the context-locked time minimal. In the driver LockLooper() is called at the latest possible time, further improving the situation a bit (keyboard/mouse response lags on high res modes). Some bitmaps were rendered in wrong colors: This was a driver fault: texture colorspaces were not always sent to the engine; The picture 'flickering' error was fixed by switching to Mesa 3.4.2.
Quake II V3.20 | http://www.bebits.com/app/1712 | Working as is. | BDirectWindow/direct mode | Doesn't call LockGL(), Destroys/recreates GLView object totally upon modeswitches (which results in driver unloading/reloading): Note, this is not a fault per se. | Driver calls LockGL() in the BGLView constructor if gl_get_current_context() returns NULL. Probably needs to be done elsewhere ('later') in the driver so it's actually possible that a context was indeed made current by calling LockGL() at some point in time. Driver explicitly Hides/Shows Window upon Show() events so Quake2 stays in direct rendering mode (R5 left-top position offset fault after issuing a 'vid_restart' from the console or switching resolutions in the game menu)

Table: Status for tested applications.
As you can see from all info listed above, the general idea for a 3D library apparantly is to make it work even if the application developer forgets to do some things officially needed. At least this is the road Be took. The downside of that is of course, that certain mistakes otherwise easily located might never be found now...
Having said that, I'll try to be as compatible as can be with the Be (software) libraries (BGLView). For now: have fun!

Rudolf.

(Page last updated on March 23, 2006)