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.

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.

Configuration

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

The following settings are defined:

• Dither

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

• 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.

• 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.

• 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.

• EnablePatchedZ

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

• ClampDelta

Caution! Experimental. When set to "On", enables clamping of various values calculated by the Permedia's delta unit.

• XLimitEnable

Caution! Experimental. When set to "On", enables early clipping of polygons before the scissor unit.

• YLimitEnable

Caution! Experimental. When set to "On", enables early clipping of polygons before the scissor unit.

• UseChromaTestABGR

Permits the incorrect use of ARGB colour values in chroma testing. This is required for proper rendering of shadows in WipeOut2097.

Radeon (R100)

Supported cards

• Radeon7000
• (todo add rest)

Configuration

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

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.