1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>GXCopyTex</TITLE> 9</HEAD> 10<BODY> 11<H1 align="left">GXCopyTex</H1> 12 13<H2>Syntax</H2> 14<dl><dd><pre class="construction"> 15#include <revolution/gx.h> 16 17void GXCopyTex( 18 void* dest, 19 <A href="../Enumerated_Types/GXBool.html">GXBool</A> clear ); 20</pre></dd></dl> 21 22<H2>Arguments</H2> 23<TABLE class="arguments" border="1" > 24 <TBODY> 25 <TR> 26<TH>dest</TH> 27<TD>Pointer to the texture image buffer in main memory. This pointer should be 32-byte aligned.</TD> 28 </TR> 29 <TR> 30<TH>clear</TH> 31<TD>When this flag is set to <CODE>GX_TRUE</CODE>, the frame buffer being copied is cleared.</TD> 32 </TR> 33 </TBODY> 34</TABLE> 35 36<H2>Return Values</H2> 37<P>None.</P> 38 39<H2>Description</H2> 40<P>This function copies the embedded frame buffer (EFB) to the texture image buffer <SPAN class="argument">dest</SPAN> in main memory. This is useful when creating textures using the gaphics processor (GP). If the <code><em><strong>clear</strong></em></code> flag is <code>GX_TRUE</code>, the EFB will be cleared to the current clear color (see the <a href="GXSetCopyClear.html"><code>GXSetCopyClear</code></a> function) during the copy operation. The source image is set by the <A href="GXSetTexCopySrc.html"><CODE>GXSetTexCopySrc</CODE></A> function. The EFB is converted to the texture format during the copy. The texture format and an optional box filter enable are set using the <A href="GXSetTexCopyDst.html"><CODE>GXSetTexCopyDst</CODE></A> function.</P> 41<P>The allocated buffer must be padded to texture tiles (32 bytes/tile) in the X and Y directions. The <A href="../Texture/GXGetTexBufferSize.html"><CODE>GXGetTexBufferSize</CODE></A> function is provided to determine the padded size.</P> 42<P>The <SPAN class="argument">clear</SPAN> flag indicates the frame buffer should be cleared during the copy operation. The frame buffer is cleared to the constant values specified by the <A href="GXSetCopyClear.html"><CODE>GXSetCopyClear</CODE></A> function.</P> 43<P><B>Note:</B> If the copy format (specified in the <A href="GXSetTexCopyDst.html"><CODE>GXSetTexCopyDst</CODE></A> function) indicates a Z copy type, then (for the purpose of copying the frame buffer) the EFB is assumed to be in RGB8 format (regardless of the value of the <A href="../PixelProc/GXSetPixelFmt.html"><CODE>GXSetPixelFmt</CODE></A> function). This has two implications if the EFB is really in RGBA6 format:</P> 44<OL> 45<LI>You cannot avoid clearing alpha when clearing RGB (the <A href="../PixelProc/GXSetAlphaUpdate.html"><CODE>GXSetAlphaUpdate</CODE></A> function is ignored). 46<LI>The clear-color value will be written to the frame buffer incorrectly (the clear-color bits [R7:R0][G7:G0][B7:B0] will be written over the EFB bits [R5:R0][G5:G0][B5:B0][A5:A0]). 47</OL> 48<P>If you plan to follow the <code>GXCopyTex</code> command with a primitive that will use the newly-copied texture, you must be sure that the texture has been completely copied out before the primitive starts to draw. You may do this by inserting the <A href="../Management/GXPixModeSync.html"><code>GXPixModeSync</code></A> function after the copy and prior to the primitive rendering.</P> 49 50<P><B>Note:</B> Even when copying within a texture buffer, the vertical filter set with <A href="GXSetCopyFilter.html"><CODE>GXSetCopyFilter</CODE></A> will still operate. You must be careful when you have configured the vertical filter to copy to the external frame buffer. 51</P> 52 53<H2>See Also</H2> 54<P class="reference"> 55<A href="GXSetTexCopySrc.html">GXSetTexCopySrc</A>, 56<A href="GXSetTexCopyDst.html">GXSetTexCopyDst</A>, 57<A href="GXSetCopyFilter.html">GXSetCopyFilter</A> 58</P> 59 60<H2>Revision History</H2> 61<P> 622007/03/05 Added note about and reference to <code>GXSetCopyFilter</code>.<br>2006/03/01 Initial version.<br> 63</P> 64 65<hr><p>CONFIDENTIAL</p></body> 66</HTML>