RENDITION . 1675 North Shoreline Blvd. Mountain View, CA 94043 650-335-5900 . http://www.rendition.com . .Rendition. .......... RRedline™ Programming Guide Guide to the RRedline HAL for Vérité™ Graphics Rendering​ RRedline​ Programming Guide GETTING STARTED ​4 WHAT IS THE VÉRITÉ? ​4 WHAT IS RREDLINE? ​4 SUPPORTED PLATFORMS ​4 SUPPORTED COMPILERS ​5 VERITE VS. REDLINE ​5 THE BUILD ENVIRONMENT ​6 BUG REPORTING ​6 TRADEMARKS ​6 HELLO TRIANGLE ​7 SOME BOOKKEEPING ​7 WRITING ERROR HANDLERS​8 INITIALIZING RREDLINE ​10 Creating the Command Buffers ​11 Surfaces ​13 Other Data Structures ​16 Specifying the Source Function ​16 UTILITIES ​16 Issuing the Command Buffer ​17 Issuing the Command Buffer ​17 Page Flipping ​18 Clearing the Back Buffer ​19 RENDERING THE TRIANGLE​20 Choosing a Vertex Type​20 Drawing Triangles ​23 SHUTTING DOWN THE VÉRITÉ ​24 MODIFICATIONS TO HELLO TRIANGLE ​26 MODIFICATION ONE: SWITCHING BETWEEN FULL SCREEN MODE AND WINDOWED MODE ​27 PAGE FLIPPING IN A WINDOW ​27 INITIALIZING BUFFERS FOR A WINDOWED APPLICATION ​28 DISPLAY SWITCHING ROUTINE ​30 DE-ACTIVATING AND RE-ACTIVATING THE APPLICATION ​31 MODIFICATION TWO: DRAWING A TEXTURE MAPPED TRIANGLE ​34 CREATING AND LOADING THE TEXTURES ​34 FILTERING THE TEXTURES​36 SETTING THE SOURCE FUNCTION ​37 RENDERING THE TRIANGLE​38 FREEING THE TEXTURES ​40 RESTORING THE TEXTURES AND PIXEL ENGINE STATE ​41 MODIFICATION THREE: Z BUFFERING AND PERSPECTIVE CORRECTION ​42 CREATING AND USING A Z-BUFFER ​42 CLEARING THE Z-BUFFER ​43 RENDERING THE TRIANGLE​43 MODIFICATION FOUR: ALPHA BLENDING ​46 ALPHA BLENDING BASICS ​46 TEXTURES WITH ALPHA ​48 RENDERING THE TRIANGLE​48 MODIFICATION FIVE: SPECULAR EXTENSIONS ​50 SPECULAR EXTENSIONS FOR THE V2000 SERIES ​50 SPECULAR ALPHA SETTINGS FOR THE V1000 ​51 RENDERING WITH SPECULAR ​53 ATTRIBUTES NOT COVERED IN EXAMPLES ​57 OPTIMIZATIONS ​58 ADD DRAWING PRIMITIVE DATA TO THE COMMAND LIST DIRECTLY ​58 CHANGE THE 3D ENGINE'S INTERNAL DATA FORMATS TO RREDLINE'S FORMATS​60 USE FAST FLOAT TO INTEGER ​60 MAINTAIN APPLICATION STATE RECORDS ​61 IMPLEMENT YOUR OWN TEXTURE CACHING ALGORITHM​62 USE VL_LOOKUP() ON SLOWER CPUS ​65 USE TRIANGLE FANS AND STRIPS WHEN POSSIBLE ​65 AVOID SURFACE LOCKS ​65 CHANGE TEXTURES IN SYSTEM MEMORY AND REDOWNLOAD RATHER THAN MODIFYING VIDEO MEMORY DIRECTLY ​65 CHOOSE THE BEST VERTEX TYPE (ESPECIALLY FOR THE V1000 SERIES) ​65 CHECK ATTRIBUTE VALUE CONSISTENCY AND REMOVE THEM FROM VERTEX TYPE​66 AVOID BLENDING AND Z BUFFERING UNLESS ABSOLUTELY NECESSARY ​66 Z BUFFER TRICKS ​67 Z BUFFER TRICKS ​67 DON'T LOCK LOTS OF SYSTEM MEMORY ​67 USE 2D BLITS RATHER THAN POLYGONS IF THAT'S WHAT'S NECESSARY ​68 REFRESH RATE ​68 USE TIME BETWEEN SWAP AND WAIT ​70 FOR ARBITRARY HOST-TO-VERITE BLITS 4-BYTE-ALIGNED DESTINATION ADDRESSES GO WAY FASTER ​70 KEEP THE VÉRITÉ BUSY ​70 AVOID VL_INSTALLTEXTUREMAP() (CALLS ~12 OTHER FUNCTIONS!) ​71 USE VL_TRIANGLEFILL() FOR FLAT SHADED TRIANGLES ​72 USE VL_PARTICLES() FOR DOTS/STARS ​72 DIFFERENT V1K/V2K TECHNIQUES ​72 TRY AN INFINITELY FAST RENDERER TO MEASURE THE APPLICATION’S “SPEED OF LIGHT” ​73 USE VL_RECTANGLE() FOR SPRITES ​73 USE VL_LOOKUP() FOR 2D STUFF (QUAKE CONSOLE/MENUS) ​73 USE MIPMAPPING ​73 COLLECT THINGS INTO LOCKED MEMORY AND USE V_ADDTODMALIST() ​74 ​Getting Started The RRedline HAL provides an interface for applications to directly access Rendition Vérité hardware for optimized 2D and 3D graphics rendering. This guide introduces RRedline and explains important concepts needed to use it. What is the Vérité? Rendition's Vérité V1000 is a single chip 2D/3D graphics engine, GUI accelerator, digital video accelerator, and VGA engine. The Vérité V2000 series of chips increase the functionality of the V1000 by adding per vertex specular, video in/out operations, and dramatically improved 2D and 3D performance. In this document, we’ll refer to both architectures as just ‘Vérité’. The Vérité employs a unique architecture, combining a fully programmable RISC core with a hard-wired pixel pipeline (known as the “Pixel Engine”). This design provides very high performance while maintaining a great deal of flexibility through the use of custom microcode. For 2D, 3D, and video operations, work is divided between the RISC and Pixel Engine. The RISC engine performs setup operations and passes drawing commands to the Pixel Engine. The Pixel Engine supports texture mapping with correct perspective, bilinear filtering, Z buffering, alpha blending, fog, and other advanced rendering features, such as color space conversion for digital video. Utilizing the Vérité RISC core for setup operations reduces the load on the CPU for 3D drawing operations such as gradient calculations. The CPU is therefore freed to perform application tasks such as simulation and other non-graphics processes. Additionally, the Vérité is a DMA busmaster, which allows it to transfer commands and data asynchronously from host memory to the Vérité command FIFO. This asynchronous operation allows both the CPU and Vérité to run at close to peak rates simultaneously. What is RRedline? RRedline was developed with the input of many game and application developers to provide a powerful, flexible interface. Only one version of a RRedline application is required to run on any of the Vérité chipsets. It is an immediate-mode, device coordinate, rasterization interface to the Vérité. The application must perform all transformation, lighting, clipping, and screen projection of vertices before sending the vertices to RRedline. RRedline is currently a fixed- point data interface to the Vérité. RRedline includes functions for memory management, command and data (texture- map) transfer, setting drawing state, and drawing primitives. Supported Platforms RRedline is a Windows 95 interface for Pentium-class PCs. Those familiar with programming the Vérité in DOS will see that RRedline bears a striking resemblance to the original Rendition Speedy3D interface. Rendition is investigating NT support for RRedline. RRedline currently supports the following graphics cards. Note that RRedline requires at least the 2.0 series of display drivers. The latest drivers have been included in the SDK for development purposes only. For final testing of products, you will want to get, at least, each vendor’s 2.0 display drivers. V2000 series cards will initially support RRedline. • Stealth II from Diamond (V2100) • Thriller 3D from Hercules (V2200) • Bonnie & Clyde by Jazz (V2200) • Outlaw 3D by Jazz (V2200) • GLadiator by DSystems (V2200) • Vision 1 from QDI (V2200) • V-Raptor 3D from Genoa Systems (V2200) • Magic Video 3D from I/O Magic (V1000) • Tornado 3D from Max 2 Tech (V1000) • Total 3D from Canopus (V1000) • 3D Blaster PCI from Creative Labs (V1000) • Intense 3D 100 from Intergraph (V1000) • miro CRYSTAL VRX from Miro (V1000) • Screamin’ 3D from Sierra On-Line (V1000) • Rendition development boards (V2200/V1000) Supported Compilers RRedline currently supports Microsoft Visual C++ (version 4.0 and later), Watcom C/C++ (version 10.5 and later), and Borland C++ (version 5.0 and later). Verite vs. Redline RRedline is comprised of two layers. The lowest layer, verite.lib, is the platform dependent Hardware Abstraction Layer (HAL). Specifically, the function categories which fall into verite.lib deal with host and video memory allocation, command transfer, and display modes. All function calls beginning with V_ are part of verite.lib. Above verite.lib sits redline.lib. This higher level library provides helper functions to ease the development process. It includes wrappers around functions dealing with the Vérité handle, memory allocation, etc. It also describes and creates the commands for the Vérité to execute. All function calls beginning with VL_ are part of redline.lib. In general, the most successful approach will be to use redline.lib extensively to develop the application, then optimize the most time-critical sections of the to develop the application, then optimize the most time-critical sections of the application by talking directly to verite.lib. The Build Environment Setting up your compiler Refer to the documentation for your compiler if you need instruction regarding this process. Includes All the necessary header files are in the include directory in the SDK. Add this directory to your include search path. If you are using any of the source code from the utils directory, the associated headers are found there; add it, too. Though your application need only include verite.h and redline.h, these files reference other files in the include directory. Libraries The RRedline import libraries for the Microsoft and Watcom compilers are in the lib directory. Libraries for the Borland compiler are located in the lib/Borland sub-directory. You can either add this directory to your library search path or specify the libraries by their full paths. Bug Reporting If you are not a member of our developer’s program, you can report bugs via Rendition’s web site. You will find a bug reporting form on the Developer page on the Rendition Web Site. If you cannot use the web-based form, fill out the form provided in doc\bugrpt.txt and email it to [email protected]. Use the words “RRedline Bug” in the subject line. Trademarks Windows 95 and Windows NT are trademarks of Microsoft. All other product names are trademarks of their respective owners. ​Hello Triangle This section contains a quick introduction to RRedline basics. By explaining each line of a simple example application along with the data structures used you’ll become acquainted with the minimum requirements necessary to get your application to run with RRedline. The code here is also quite reusable requiring little or no modification to get it to work in your own applications. The code we’re going to describe here and in later examples is complete and runs well on the Vérité. However, for real applications you’ll want to modify your routines according to the methods discussed in the chapter titled Optimizations. This will result in the best performance on our hardware. The example we are going to use draws a flat shaded red triangle in the middle of the entire screen.