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<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><CODE>#include <revolution/gx.h></CODE></PRE> 16 <DD> 17<PRE><CODE>void GXCopyTex( 18void* dest, 19<a href="../Enumerated_Types/GXBool.html">GXBool</a> clear );</CODE></PRE> 20</DL> 21<H2>Arguments</H2> 22<TABLE border="1" cellpadding="3" cellspacing="0.1"> 23 <TBODY> 24 <TR> 25<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>dest</CODE></STRONG></EM></TD> 26<TD width="520"><SPAN>Pointer to the texture image buffer in main memory. This pointer should be 32-byte aligned.</SPAN></TD> 27 </TR> 28 <TR> 29<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>clear</CODE></STRONG></EM></TD> 30<TD width="520"><SPAN>When this flag is set to <CODE>GX_TRUE</CODE>, the frame buffer being copied is cleared.</SPAN></TD> 31 </TR> 32 </TBODY> 33</TABLE> 34<H2>Return Values</H2> 35<P>None.</P> 36<H2>Description</H2> 37<P>This function copies the Embedded Frame Buffer (EFB) to a texture image buffer <code><em><strong>dest</strong></em></code> 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 described by <a href="GXSetTexCopySrc.html"><code>GXSetTexCopySrc</code></a>. The EFB is converted to the texture format during the copy. The texture format and an optional box filter enable are set using <a href="GXSetTexCopyDst.html"><code>GXSetTexCopyDst</code></a>.</P> 38<P>The allocated buffer must be padded to texture tiles (32B/tile) in X and Y. The function <a href="../Texture/GXGetTexBufferSize.html"><code>GXGetTexBufferSize</code></a> is provided to determine the padded size.</P> 39<P>The <em><strong><code>clear</code></strong></em> flag indicates the frame buffer should be cleared during the copy operation. The frame buffer is cleared to the constant values specified by <code><a href="GXSetCopyClear.html">GXSetCopyClear</a></code>.</P> 40<P><B>Note:</B> If the copy format (specified in <a href="GXSetTexCopyDst.html"><code>GXSetTexCopyDst</code></a>) indicates a <EM>Z</EM>-copy type, then (for the purpose of clearing the frame buffer) the EFB is assumed to be in <EM>RGB8</EM> format (regardless of the value of <a href="../PixelProc/GXSetPixelFmt.html"><code>GXSetPixelFmt</code></a>). This has two implications if the EFB is really in <EM>RGBA6</EM> format:</P> 41<OL> 42<LI>You cannot avoid clearing alpha when clearing RGB (<a href="../PixelProc/GXSetAlphaUpdate.html"><code>GXSetAlphaUpdate</code></a> is ignored). 43<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]). 44</OL> 45<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 a <a href="../Management/GXPixModeSync.html"><code>GXPixModeSync</code></a> command after the copy and prior to the primitive.</P> 46 47<P><B>Note:</B> Since the vertical filter set by <A href="GXSetCopyFilter.html"><CODE>GXSetCopyFilter</CODE></A> is used even when copying with the texture buffer, care is required when setting a vertical filter for copying to the external frame buffer. 48</P> 49 50<H2>See Also</H2> 51<P><A href="GXSetTexCopySrc.html"><CODE>GXSetTexCopySrc</CODE></A><br> <A href="GXSetTexCopyDst.html"><CODE>GXSetTexCopyDst</CODE></A><br> <A href="GXSetCopyFilter.html"><CODE>GXSetCopyFilter</CODE></A> 52</P> 53<H2>Revision History</H2> 54<P> 552007/3/5 Added a link and a note for <code>GXSetCopyFilter</code>.<br>2006/03/01 Initial version. 56</P> 57<hr><p>CONFIDENTIAL</p></body> 58</HTML>