View source for 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.
* ENVARC:Warp3D/
:This directory contains settings for Warp3D and it's drivers.

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 ENVARC: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.