#include <revolution/gx.h>volatile void* GXRedirectWriteGatherPipe( void * ptr );ptr |
A pointer to a 32-byte aligned target buffer. |
The actual address of the write gather port. All writing to the this address are collected to the write gather pipe. The GXWGFifo union can also be used. If the GXWGFifo union is not used, be certain the local variables are volatile. Failure to do so can result in an optimization exception when the compiler is writing to the same pointer.
This advanced API temporarily redirects the write gather pipe to a new location. Ordinarily, the GX library sets up the write gather pipe to efficiently write command data to memory.
After calling this function, subsequent writes to the address returned by this function (or the GXWGFifo union) will be gathered and sent to a destination buffer. The write pointer is automatically incremented by the GP. The write gather pipe can be restored by calling GXRestoreWriteGatherPipe. This function cannot be called between a GXBegin/GXEnd pair. Note: No GX commands can be called until the write gather pipe is restored. You must call GXRestoreWriteGatherPipe before calling this function again, or else the final call to restore the pipe will fail.
The destination buffer, referred to by ptr, must be 32-byte aligned. The amount of data written should also be 32-byte aligned. If it is not, zeroes will be added to pad the destination buffer to 32B. No part of the destination buffer should be modified inside the CPU caches - this may introduce cache incoherency problems.
The write gather pipe is one of the fastest ways to move data out of the CPU (the other being the locked cache DMA). In general, you are compute-bound when sending data from the CPU. In our tests, we have achieved approximately 1.12 GB/s sustained bandwidth to write trivial data with this API (assuming full speed external bus; on 75% systems, expect about 858 MB/s). In DEBUG builds, expect only half of the bandwidth performance because the compiler will generate extraneous loads.
This function is more economical than creating a fake CPU FIFO in a send destination buffer, which requires calls to GXSetCPUFifo and GXInitFifoBase. This function performs very light weight state saves by assuming that the CPU and GP fifos never change.
03/01/2006 Initial version.