UserDoc:Warp3D

Warp3D User Guide

Overview

Warp3D is an Application Programming Interface (API) and driver system that allows software to utilise hardware accelerated 3D on supported graphics cards. Through Warp3D, applications can offload the drawing of polygon based graphics to the graphics card without having to know the specific details of the hardware in use.

Background

Warp3D was conceived as a lightweight driver and originally developed for 68K based machines running AmigaOS 3, with support for PowerPC applications running under WarpOS. At that time, only a limited number of cards were available for the Amiga that offered any form of 3D support. These early devices had numerous limitations and this was reflected in the design and implementation of Warp3D. A key limitation of the originally supported hardware that has in turn shaped the evolution of Warp3D is that it accelerated the drawing stages only. Likewise, Warp3D abstracted only these drawing stages and it was the responsibility of the software to perform any necessary 3D calculations. Drawing, or to use the more technical term, rasterization, is typically the last step in a 3D graphics system. As a consequence, Warp3D is not an alternative or replacement for OpenGL.

Components

Warp3D is split into several parts with different responsibilities as follows.

• LIBS:Warp3D.library

The main library as used by application software.

• LIBS:Warp3D/GFXDrivers/

This directory contains drivers that abstract the allocation of resources on the graphics card. Historically, access to these resources was controlled by whichever Retargetable Graphics (RTG) system was in use and so this contained drivers for both the CyberGraphX and Picasso96 RTG systems. Since AmigaOS 4, only Picasso96 is supported.

• LIBS:Warp3D/HWDrivers/

This directory contains drivers for specific 3D chips. The main library will automatically pick the most appropriate driver from this directory.

• ENV:Warp3D/

This directory contains settings for Warp3D and it's drivers. As expected, these are stored permanently in ENVARC:Warp3D/

Please note that, in contrast with versions for AmigaOS 3, any installed version of LIBS:Warp3DPPC.library is not part of Warp3D in AmigaOS 4. This is a stub library that forms part of the WarpOS emulation package and is required to support legacy WarpOS based Warp3D software.

Current version

Version 5 as shipped with AmigaOS 4 adds several new features but remains a rasterizer-only implementation. Presently supported cards such as the Radeon7000 and higher are able to accelerate more than just drawing and as such are underutilized by Warp3D. For this reason Warp3D is considered legacy software and will some stage be deprecated in favour of a more complete driver system.

Configuration

The hardware supported by Warp3D varies considerably in performance, implementation and available capabilities. For this reason, each driver is separately configurable through the use of environment variables. These settings are located in driver-specific subdirectories of the main ENV:Warp3D/ directory.

Application Profiles

Over time, the addition of new features and correction of bugs has resulted in a situation where compatibility with older titles has been affected. For example, in version 4 of Warp3D, an update to the Permedia2 driver added a new blending mode. While this was required for MiniGL titles such as Heretic 2, it resulted the famous "engine trail" bug in WipeOut 2097. Although the feature could be turned on and off through the use of an environment variable, there was no way to have a single configuration suitable for all.

To address this problem, a feature has been added to selected drivers in Warp3D 5 that allows the driver configuration to be overridden on a per application basis. This works through the use of appropriately named subdirectories within the driver's own environment directory. The general path to these settings is ENV:Warp3D/<driver name>/<application name>/. Thus, when the application "ShootEmUpFTW" running on a Radeon 9250 allocates the 3D resources, the driver checks to see whether any of the driver's environment settings in the ENV:Warp3D/RadeonR200/ directory have also been set in the ENV:Warp3D/RadeonR200/ShootEmUpFTW/ directory. Any that have will override those in the main ENV:Warp3D/RadeonR200/ directory. This ensures that only those settings requiring customisation need be defined, rather than duplicating all of the settings.

Using DOS Commands

The simplest way to set and unset environment variables is to use the SetEnv and UnSetEnv DOS commands. For example, from the shell type

SetEnv SAVE Warp3D/RadeonR200/Anisotropic on

and it will enable Anisotropic mode for all applications using the R200.

If you wanted to enabled Anisotropic mode for only GLQuake the correct command would be

SetEnv SAVE Warp3D/RadeonR200/GLQuake/Anisotropic on

To unset an environment variable just use UnSetEnv instead of SetEnv as follows

UnSetEnv DELETE Warp3D/RadeonR200/GLQuake/Anisotropic

The directories and files can also be manipulated directly but using the DOS commands is easier and guaranteed to be backwards compatible.

Note
In the driver specific documentation that follows, all settings marked as experimental may be changed or removed without warning in future releases.

Permedia 2

The Permedia2 represents the oldest supported 3D hardware in AmigaOS 4. Whilst used on the most powerful graphics cards ever specifically built for the classic Amiga, this device lacks many features considered standard for 3D hardware that has become available since the advent of generic PCI expansions and systems build specifically for AmigaOS 4.

Supported cards

• BlizzardVisionPPC 8MB
• CyberVisionPPC 8MB

In addition, generic 8MB PCI cards may work but have not been tested.

General tips

The lack of video memory on this card, combined with the comparatively slow interface means that it's important to save as much video memory as possible before running any 3D game. Where possible:

• Close or reduce the size / colour depth of your Workbench screen
• If a title allows it, use a conservative screen size, for example, 640x480 @ 16-bit
• If a title allows it, consider using lower detail textures
• If a title allows it, stick to double buffering or windowed mode.
• If a title does not provide user control over texture detail and makes use of large textures, you may be able to force it to use lower detail versions by setting the LimitTextureSize variable. This requires that the application queries the driver capabilities and respects the maximum texture size that it reports by downsampling textures larger than the limit.

Configuration

• The environment settings for the Permedia2 driver are located in ENV:Warp3D/Permedia2/
• Environment variable values are not case sensitive.
• The Permedia2 driver supports application profiles.

The following settings are defined and can all be overridden for any application:

• Dither

When set to "on", forces the use of dithering on 15/16-bit displays, whether the application enables it or not.

When set to "off", the application decides whether dithering is enabled on 15/16-bit displays.

• Fog

When set to "linear", fakes linear fogging through interpolation.

When set to "all", allows any fogging mode to be used, but will be still implemented as interpolated.

• DisableAdditiveBlending

When set to "on", disables support for additive blending. This fixes the exhaust trail bug in WipeOut 2097.

When set to "off", support for additive blending is enabled. In the absence of any manual value, this is the default setting.

• DisableFBClear

When set to "on", disables clearing of the framebuffer via Warp3D. This only makes sense for applications which redraw the whole screen every frame but still insist on clearing the buffer.

When set to "off", the framebuffer will be cleared by Warp3D. In the absence of any manual value, this is the default setting.

• DisableSubpatchedTextures

When set to "on", disables the use of subpatched textures. This only makes sense if you experience unusual texture corruption or when a title makes heavy use of texture updates.

When set to "off", sub patched textures are enabled, improving the performance of texture mapping. In the absence of any manual value, this is the default setting.

• EnablePatchedZ

When set to "on", enables tiled Z buffer. This typically improves performance of depth buffering, but presently breaks compatibility with applications making use of software Z buffer access.

When set to "off", disables tiled Z buffer. In the absence of any manual value, this is the default setting.

• ClampDelta

Caution! This feature is experimental.

When set to "on", enables clamping of various values calculated by the Permedia's delta unit.

When set to "off", no delta unit clamping is applied. In the absence of any manual value, this is the default setting.

• XLimitEnable

Caution! This feature is experimental.

When set to "on", enables early horizontal clipping of polygons before the scissor unit. This may improve performance for applications which rely on scissoring to perform clipping of large polygons that are mostly outside the scissor area.

When set to "off", no X limits testing is performed. In the absence of any manual value, this is the default setting.

• YLimitEnable

Caution! This feature is experimental.

When set to "on", enables early vertical clipping of polygons before the scissor unit. This may improve performance for applications which rely on scissoring to perform clipping of large polygons that are mostly outside the scissor area.

When set to "off", no Y limits testing is performed. In the absence of any manual value, this is the default setting.

• UseChromaTestABGR

When set to "on", interprets the colour format used for chroma testing to be ABGR, rather than the correct RGBA format. Older versions of the Permedia2 driver incorrectly implemented chroma testing using the hardware native ABGR format. Some applications, e.g: WipeOut2097, expect this to be the case and will not render transparency properly without it.

When set to "off", interprets the colour format to be RGBA as specified by the API. In the absence of any manual value, this is the default setting.

• LimitTextureSize

Normally, the Permedia2 permits textures up to 2048 pixels and applications which query Warp3D to determine the largest size for a texture will be given this value. Thus an application may try to allocate textures that, while legal, are impractically large. This parameter allows control over the value that is reported by the driver. Legal values are 128, 256, 512, 1024 and 2048. Any other values will be rounded to the nearest supported power of 2.

Unsupported features

The Permedia2 lacks direct support for the following Warp3D features

• Multitexturing
• MIP Mapping
• Stencil buffer
• Blend functions other than alpha blending and a partial additive blend implementation
• Fog functions other than interpolated
• Gouraud shaded vertex alpha values

Voodoo (Avenger)

Configuration

• The environment settings for the Voodoo Avenger driver are located in ENV:Warp3D/Avenger/
• Environment variable values are not case sensitive.
• The Avenger driver does not yet support application profiles.

The following settings are defined:

• Dither

When set to "on", forces the use of dithering on 15/16-bit displays, whether the application enables it or not.

When set to "off", the application decides whether dithering is enabled on 16-bit displays.

Voodoo (Napalm)

Configuration

• The environment settings for the Voodoo Napalm driver are located in ENV:Warp3D/Napalm/
• Environment variable values are not case sensitive.
• The Avenger driver does not yet support application profiles.

The following settings are defined:

• Dither

When set to "on", forces the use of dithering on 15/16-bit displays, whether the application enables it or not.

When set to "off", the application decides whether dithering is enabled on 16-bit displays.

• DitherAlgo

When set to "4x4", uses a 16-pixel sample area for ordered dithering.

When set to "2x2", uses a 4-pixel sample area for ordered dithering. In the absence of any manual setting, this is the default.

• AntiAlias

When set to "on", enables support for fullscreen antialiasing (FSAA) with applications that support it. This requires the allocation of a secondary framebuffer which is 4x larger than the visible display and may impact performance significantly depending on the amount of VRAM and the fillrate.

When set to "off", no support for FSAA is available. In the absence of any manual setting, this is the default.

Radeon (R100)

Supported cards

• Radeon7000

General tips

Radeon cards with 64MB or less of Video RAM may be at a disadvantage when running 3D applications that expect more memory to be available for textures and buffers. To save memory, consider the following

• Disabling compositing for Workbench screen.
• Switching to 16-bit screen depth for workbench screen.
• For applications not requiring stencil buffer support (which includes all legacy titles written prior to AmigaOS 4) or software Z-buffer access, setting the Use16BitZBuffer environment variable. This halves the amount of Video RAM required for Z buffering.

Configuration

• The environment settings for the Radeon driver are located in ENV:Warp3D/Radeon/
• The Radeon driver supports application profiles.

The following settings are defined and can all be overridden for any application:

• Anisotropic

When set to "on", enables support for anisotropic filtering. This improves the quality of textures that are viewed at sharp angles.

When set to "force", forces anisotropic filtering to be used. Many legacy applications were written before hardware supporting this feature were available and have no internal support.

When set to "off", disables support for anisotropic filtering. In the absence of any manual value, this is the default setting.

• MaxAnisotropic

Sets the maximum anisotropy. Legal values are 1, 2, 4, 8 and 16. All other values will be interpreted as 1.

• Dither

When set to "on", forces the use of dithering on 15/16-bit displays, whether the application enables it or not.

When set to "off", the application decides whether dithering is enabled on 15/16-bit displays.

• DisableFBClear

When set to "on", disables clearing of the framebuffer via Warp3D. This only makes sense for applications which redraw the whole screen every frame but still insist on clearing the buffer.

When set to "off", the framebuffer will be cleared by Warp3D. In the absence of any manual value, this is the default setting.

• UseChromaTestUpper

The Warp3D API specifies both a lower and upper bound for chroma testing a range of colours. However, the Radeon only supports a single colour for chroma testing purposes. This suits many applications which simply want to make a particular colour transparent.

When set to "on", selects the upper boundary colour to be used for single colour chroma testing.

When set to "off", selects the lower boundary colour to be used for single colour chroma testing. In the absence of any manual value, this is the default setting.

• UseChromaTestABGR

When set to "on", interprets the colour format used for chroma testing to be ABGR, rather than the correct RGBA format. Older versions of the Permedia2 driver incorrectly implemented chroma testing using the hardware native ABGR format. Some applications, e.g: WipeOut2097, expect this to be the case and will not render transparency properly without it.

When set to "off", interprets the colour format to be RGBA as specified by the API. In the absence of any manual value, this is the default setting.

• ForceChromaTest

When set to "on", forces chroma testing to be enabled. This is a brute force fix for titles like WipeOut2097, to render chroma tested transparency correctly but forget to correctly enable the state.

When set to "off", defers control of chroma testing to the application. In the absence of any manual value, this is the default setting.

• Use16BitZBuffer

When set to "on", causes Z buffer format to change from 24-bit to 16-bit and disables all support for the stencil buffer (which together with the 24-bit Z buffer is stored as a 32-bit combined buffer). All applications written for Warp3D v4 or earlier have no access to stencil support. Switching to 16-bit reduces Video RAM usage and doubles the effective Z buffer bandwidth, at a slight loss in precision.

When set to "off", Z buffer depth is 24-bit. In the absence of any manual value, this is the default setting.

• MaxPacketSize

Caution! This feature is experimental.

Sets a limit on the maximum amount of data that can be sent to the card as a single render command. Lowering this value may improve performance for some titles that make heavy use of large vertex array drawing.

The valid range for this value is 1024 - 7800. Values outside this range will be clamped. In the absence of any manual value, 7800 is the default setting.

Radeon (R200)

Supported cards

• Radeon 9250
• (todo add rest)

Configuration

• The environment settings for the Radeon R200 driver are located in ENV:Warp3D/RadeonR200/
• The RadeonR200 driver supports application profiles.

The following settings are defined and can all be overridden for any application:

• Anisotropic

When set to "on", enables support for anisotropic filtering. This improves the quality of textures that are viewed at sharp angles.

When set to "force", forces anisotropic filtering to be used. Many legacy applications were written before hardware supporting this feature were available and have no internal support.

When set to "off", disables support for anisotropic filtering. In the absence of any manual value, this is the default setting.

• MaxAnisotropic

Sets the maximum anisotropy. Legal values are 1, 2, 4, 8 and 16. All other values will be interpreted as 1.

• Dither

When set to "on", forces the use of dithering on 15/16-bit displays, whether the application enables it or not.

When set to "off", the application decides whether dithering is enabled on 15/16-bit displays.

• DisableFBClear

When set to "on", disables clearing of the framebuffer via Warp3D. This only makes sense for applications which redraw the whole screen every frame but still insist on clearing the buffer.

When set to "off", the framebuffer will be cleared by Warp3D. In the absence of any manual value, this is the default setting.

• UseChromaTestUpper

The Warp3D API specifies both a lower and upper bound for chroma testing a range of colours. However, the Radeon only supports a single colour for chroma testing purposes. This suits many applications which simply want to make a particular colour transparent.

When set to "on", selects the upper boundary colour to be used for single colour chroma testing.

When set to "off", selects the lower boundary colour to be used for single colour chroma testing. In the absence of any manual value, this is the default setting.

• UseChromaTestABGR

When set to "on", interprets the colour format used for chroma testing to be ABGR, rather than the correct RGBA format. Older versions of the Permedia2 driver incorrectly implemented chroma testing using the hardware native ABGR format. Some applications, e.g: WipeOut2097, expect this to be the case and will not render transparency properly without it.

When set to "off", interprets the colour format to be RGBA as specified by the API. In the absence of any manual value, this is the default setting.

• ForceChromaTest

When set to "on", forces chroma testing to be enabled. This is a brute force fix for titles like WipeOut2097, to render chroma tested transparency correctly but forget to correctly enable the state.

When set to "off", defers control of chroma testing to the application. In the absence of any manual value, this is the default setting.

• Use16BitZBuffer

When set to "on", causes Z buffer format to change from 24-bit to 16-bit and disables all support for the stencil buffer (which together with the 24-bit Z buffer is stored as a 32-bit combined buffer). All applications written for Warp3D v4 or earlier have no access to stencil support. Switching to 16-bit reduces Video RAM usage and doubles the effective Z buffer bandwidth, at a slight loss in precision.

When set to "off", Z buffer depth is 24-bit. In the absence of any manual value, this is the default setting.

• MaxPacketSize

Caution! This feature is experimental.

Sets a limit on the maximum amount of data that can be sent to the card as a single render command. Lowering this value may improve performance for some titles that make heavy use of large vertex array drawing.

The valid range for this value is 1024 - 7800. Values outside this range will be clamped. In the absence of any manual value, 7800 is the default setting.