Table of Contents Glide Programming Guide
Chapter 11. Accessing the Linear Frame Buffer
Download 6.22 Mb.
|
- Navigate this page:
- 2Acquiring an LFB Read or Write Pointer
Chapter 11. Accessing the Linear Frame Buffer1In This ChapterThe frame buffer on a Voodoo Graphics subsystem is directly accessible by software as a single linear address space. This address space is segmented into separate readable and writable areas, and each of these areas in turn can address any of the three hardware buffers: the front buffer, the back buffer, or the auxiliary buffer. You will learn how to: calculate a pixel address acquire an LFB (linear frame buffer) read or write pointer read pixel data from the color, alpha, or depth buffer write pixel data in a user-selectable format to the color alpha, or depth buffer set constant values for direct writes to the depth and alpha buffers enable and disable the pixel pipeline during direct LFB writes Warning: The linear frame buffer interface was extensively modified in the Glide 2.2 release. The following routines are now obsolete: grLfbBegin(), grLfbEnd(), grLfbGetReadPtr(), grLfbGetWritePtr(), grLfbBypassMode(), grLfbWriteMode(), and grLfbOrigin(). 2Acquiring an LFB Read or Write PointerWhen a Glide application desires direct access to a color or auxiliary buffer, it must lock that buffer in order to gain access to a pointer in the frame buffer data. This lock may assert a critical code section which affects process scheduling and precludes the use of GUI debuggers; therefore, time spent doing direct accesses should be minimized and the lock should be released as soon as possible. FxBool grLfbLock( GrLock_t type, GrBuffer_t buffer, GrLfbWriteMode_t writeMode, GrOriginLocation_t origin, FxBool pixelPipeline, GrLfbInfo_t *info ) An application may hold multiple simultaneous locks to various buffers, if the underlying hardware allows it. Application software should always check the return value of grLfbLock(): a lock may fail. A buffer is locked for reads or for writes, as specified in the type parameter. type is a bit field created by ORing a read/write flag and an idle flag. The read/write flag can be either GR_LFB_READ_ONLY and GR_LFB_WRITE_ONLY. The idle flag can be either GR_LFB_IDLE or GR_LFB_NOIDLE. The default is GR_LFB_IDLE: the graphics subsystem will be idle until the buffer is unlocked. GR_LFB_NOIDLE allows the pixel pipeline to continue operating during the lock: triangle rendering and buffer clearing operations may be interspersed with frame buffer accesses. WARNING: using GR_LFB_NOIDLE may interfere with sound generation. The buffer parameter specifies which Glide buffer to lock; currently supported buffer designations are GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, and GR_BUFFER_AUXBUFFER. If the graphics hardware supports multiple write formats to the linear frame buffer space, an application may request a particular write format with the writeMode parameter; valid values are listed below.
Use GR_LFBWRITEMODE_ANY when acquiring a read-only LFB pointer or when you want to use the existing data format. If the data format specified in writeMode is not supported on the target hardware, the lock will fail. Supported pixel formats are described in Table Accessing the Linear Frame Buffer.2 and Table Accessing the Linear Frame Buffer.3, later in this chapter. If the application specifies GR_LFB_WRITEMODE_ANY and the lock succeeds, the destination pixel format will be returned in info.writeMode. This default destination pixel format will always be the pixel format that most closely matches the true pixel storage format in the frame buffer. On Voodoo Graphics and Voodoo Rush, this will always be GR_LFBWRITEMODE_565 for color buffers and GR_LFBWRITEMODE_ZA16 for the auxiliary buffer. The writeMode argument is ignored for read-only locks. Some 3Dfx hardware supports a user-specified y origin for LFB writes. An application may request a particular y origin by passing an origin argument other than GR_ORIGIN_ANY. If the origin specified is not supported on the target hardware, then the lock will fail. If the application specifies GR_ORIGIN_ANY and the lock succeeds, the LFB y origin will be returned in info.origin. The default y origin for LFB writes is GR_ORIGIN_UPPER_LEFT; currently supported values are GR_ORIGIN_UPPER_LEFT, GR_ORIGIN_LOWER_LEFT, and GR_ORIGIN_ANY. Some 3Dfx hardware allows linear frame buffer writes to be processed by the pixel pipeline before being written into the selected buffer. This feature is enabled by passing a value of FXTRUE in the pixelPipeline argument; grLfbLock() will fail if the underlying hardware is incapable of processing pixels through the pixel pipeline. When enabled, color, alpha, and depth data from the linear frame buffer write will be processed as if it were generated by the triangle iterators. If the selected writeMode lacks depth information, then the depth value is derived from grLfbConstantDepth(). If the writeMode lacks alpha information, then the alpha value is derived from grLfbConstantAlpha(). Linear frame buffer writes through the pixel pipeline may not be enabled for auxiliary buffer locks. The pixelPipeline argument is ignored for read-only locks. The final parameter to grLfbLock() is a structure of type GrLfbInfo_t. The info.size is used to provide backward compatibility for future revisions of grLfbLock() and must be initialized by the user to the size of the GrLfbInfo_t structure, as shown below. An unrecognized size will cause the lock to fail. info.size = sizeof( GrLfbInfo_t ); Upon successful completion, the rest of the structure will be filled in with information pertaining to the locked buffer. The GrLfbInfo_t structure is defined as: typedef struct { int size; void *lfbPtr; FxU32 strideInBytes; GrLfbWriteMode_t writeMode; GrOriginLocation_t origin; } GrLfbInfo_t; info.lfbPtr is assigned a valid linear pointer to be used for accessing the requested buffer. The access is either read-only or write-only; reading from a write pointer or writing to a read pointer will have undefined effects on the graphics subsystem. info.strideInBytes is assigned the byte distance between scanlines. As described above, info.writeMode and info.origin are filled in with values describing the settings in use in the currently selected buffer. A successful call to grLfbLock() will cause the 3D graphics engine to idle. This is equivalent to calling grSstIdle() and may negatively impact the performance of some applications. Writes to the linear frame buffer should use grLfbWriteRegion(), described later in this chapter, to interleave ordered linear frame buffer copies into the 3D command stream as efficiently as possible. When the application has completed its direct access transactions, the lock is relinquished by calling grLfbUnlock(), thus restoring 3D and GUI access to the buffer. FxBool grLfbUnlock( GrLock_t type, GrBuffer_t buffer ) The two parameters, type and buffer, are identical to the first two arguments of the corresponding call to grLfbLock(). Note that after a successful call to grLfbUnlock(), accessing the info.lfbPtr used in the grLfbUnlock() call will have undefined results. An application may not call any Glide routines other than grLfbLock() and grLfbUnlock() while any lock is active. Any such calls will result in undefined behavior. Download 6.22 Mb. Share with your friends:
|