1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<TITLE>CARD Banners and Icons</TITLE> 9</HEAD> 10<BODY> 11<H1>CARD Banners and Icons</H1> 12<H2>Introduction</H2> 13<P>You can separately set icons, banners, and comments for GameCube Memory Cards (referred to as "Memory Cards") that are compatible with Revolution. A Memory Card must have at least one 32x32 icon to display in the Revolution system menu, and two 32-byte long character strings (not null-terminated). The 96x32 banner is optional. Banners and icons have two formats: RGB5A3 or C8 (the formats can be mixed for icons if desired). The minimum size requirement for system information is a 32x32 C8 icon and a 64-byte comment string that is 1600 bytes.</P> 14<P><STRONG>Note:</STRONG> 15Creating a banner icon is unnecessary for normal programs that only perform read processing.</P> 16<H2>Saving Icons, Banner, and Comments</H2> 17<P>Icon, banner, and comment data are stored in the data block of the file in the user section. The comment block must not cross the 8-KB boundary of the file (i.e., the comment data must fit an 8-KB block of the file). In the file, icon and banner information must be located between offset 0 and offset 511 bytes.</P> 18<P>Icon and banner data must be stored in the specific format that follows: </P> 19<BLOCKQUOTE> 20<PRE>----------- 21banner_texel (optional) 22banner_CLUT (if the banner format is C8) 23----------- 24icon0_texel (required) 25icon1_texel (optional) 26. 27. 28. 29icon7_texel (optional) 30icon_CLUT (if the icons are C8 format) 31-----------</PRE> 32</BLOCKQUOTE> 33<P>The banner is optional. If the banner is in <CODE>C8</CODE> format, then <CODE>CLUT</CODE> must follow the banner texel information. If <CODE>C8</CODE> format is not used, then <CODE>CLUT</CODE> is not required. At least one icon must follow the banner, but you can have a maximum of seven icons. The icon texel data must be in sequential order. If the icons are in <CODE>C8</CODE> format, a shared <CODE>CLUT</CODE> must follow all the texel information.</P> 34<P>As an example, if you wish to have an <CODE>RGB5A</CODE> banner with four <CODE>C8</CODE> icons, the following would be the format: </P> 35<BLOCKQUOTE> 36<PRE>----------- 37banner_texel (6144 bytes) 38----------- 39icon0_texel (1024 bytes) 40icon1_texel (1024 bytes) 41icon2_texel (1024 bytes) 42icon3_texel (1024 bytes) 43icon_CLUT (512 bytes) 44-----------</PRE> 45</BLOCKQUOTE> 46<H2>Icon and Banner Data</H2> 47<P>Banner information is part of the optical disc system. Each game must create an <font face="Courier New">opening.bnr</font> file that exists in the root directory of the Disc. If you chose to use the banner with a Memory Card file, the <CODE>opening.bnr</CODE> file can be read into memory and a <CODE>DVDBanner</CODE> pointer can be pointed to the banner. The image data is contained in the <CODE>image</CODE> member. However, the <CODE>DVDBanner</CODE> image data can only be in <tt>RGB5A3</tt> format. Refer to <CODE>DVDBanner.h</CODE> for more details. Also refer to the <CODE>makebanner.exe</CODE> utility program used to generate <CODE>opening.bnr</CODE>.</P> 48<BLOCKQUOTE> 49<PRE>usage: makebanner banner.tpl banner.txt 50 51banner.tpl format: 96x32,RGB5A3 52banner.txt format (separated by newline): 53title(32 bytes) Dolphin SDK 54maker(32 bytes) Nintendo 55title(64 bytes) Dolphin Software Development Kit 56maker(64 bytes) Nintendo 57comment(128 bytes) (C)1999-2001 Nintendo. All rights reserved.</pre> 58<STRONG> 59Note: 60</STRONG> 61Comment can be on two lines. 62</BLOCKQUOTE> 63<P>Icon data should be raw texel (and <CODE>CLUT</CODE>) data in the standard Nintendo GameCube texture formats.</P> 64<H2>Setting Format Information with CARDStat</H2> 65<P>The <CODE>CARDStat</CODE> structure information is stored in the five system blocks reserved in the Memory Card. Therefore, the only information that you need to store to a Memory Card is the icon data, the comment strings (two 32-byte character strings), and the optional banner image.</P> 66<BLOCKQUOTE> 67<PRE><CODE>typedef struct CARDStat 68{ 69 // read only (Set by CARDGetStatus) 70 char fileName[CARD_FILENAME_MAX]; 71 u32 length; 72 u32 time; 73 // seconds since 01/01/2000 midnight 74 u8 gameName[4]; 75 u8 company[2]; 76 77 // read/write (Set by CARDGetStatus/CARDSetStatus) 78 u8 bannerFormat; 79 u32 iconAddr; 80 // offset to the banner, bannerTlut, icon, iconTlut data set. 81 u16 iconFormat; 82 u16 iconSpeed; 83 u32 commentAddr; // offset to the pair of 32 byte character strings. 84 85 // read-only (Set by CARDGetStatus) 86 u32 offsetBanner; 87 u32 offsetBannerTlut; 88 u32 offsetIcon[CARD_ICON_MAX]; 89 u32 offsetIconTlut; 90 u32 offsetData; 91} CARDStat;</CODE></PRE> 92</BLOCKQUOTE> 93<P>The <CODE>CARDStat</CODE> structure is used to transfer banner, icon, and comment information to the Memory Card system information. Once a file has been created, the <CODE><a href="CARDGetStatus.html">CARDGetStatus</a></CODE> function is used to retrieve the current system information for that file. The default file will have no icon, banner, or comment information. For this purpose, you must set the icon, banner, and comment information by modifying the writable members of the structure as indicated by the comments. These settings must be stored in the Memory Card using the <CODE><a href="CARDSetStatus.html">CARDSetStatus</a></CODE> function.</P> 94<P>The banner and icons example is continued. A comment string is placed before the banner at the beginning of the file. All files must have a size that is a multiple of the sector size (8 KB by default). The following example uses four sectors. The following is an example of the data layout:</P> 95<BLOCKQUOTE> 96<PRE>----------- 0 97comments (64 bytes) 98----------- 64 99banner_texel (6144 bytes) 100----------- 6208 101icon0_texel (1024 bytes) 102icon1_texel (1024 bytes) 103icon2_texel (1024 bytes) 104icon3_texel (1024 bytes) 105icon_CLUT (512 bytes) 106----------- 10496 107game data (22272 bytes) 108----------- 32768</PRE> 109</BLOCKQUOTE> 110<P>The <CODE>CARDStatus</CODE> structure members are set using the <A href="CARDGetStatus.html"><CODE>CARDGetStatus</CODE></A>, <A href="CARDSetIconFormat.html"><CODE>CARDSetIconFormat</CODE></A>, and <A href="CARDSetBannerFormat.html"><CODE>CARDSetBannerFormat</CODE></A> functions as follows:</P> 111<BLOCKQUOTE> 112<PRE><CODE> CARDStat stat; 113 114 CARDGetStatus(..., &stat); 115 116 stat->commentAddr = 0; // Beginning of file 117 stat->iconAddr = 64; // End of comment strings 118 119 // Banner Format 120 CARDSetBannerFormat(stat, CARD_STAT_BANNER_RGB5A3); 121 122// icon formats 123CARDSetIconFormat(stat, 0, CARD_STAT_ICON_C8); 124CARDSetIconFormat(stat, 1, CARD_STAT_ICON_C8); 125CARDSetIconFormat(stat, 2, CARD_STAT_ICON_C8); 126CARDSetIconFormat(stat, 3, CARD_STAT_ICON_C8);</CODE></PRE> 127</BLOCKQUOTE> 128<H2>Setting Icon Speed and Animation with CARDStat</H2> 129<P>You can use up to eight frames of animation using the file icons. Three wait time lengths (slow, middle, and fast) can be set between each animation frame. The speed is determined by the screen refresh rate (60Hz or 50Hz). The wait time lasts the following number of refresh frames:</P> 130<TABLE border="1" cellpadding="3" cellspacing="0.1"> 131 <TBODY> 132 <TR> 133<TD bgcolor="#C0C0C0"><B>Definition</B></TD> 134<TD bgcolor="#C0C0C0"><B>Number of Frames</B></TD> 135 </TR> 136 <TR> 137<TD><CODE><CODE>CARD_STAT_SPEED_SLOW</CODE></CODE></TD> 138 <TD>12</TD> 139 </TR> 140 <TR> 141<TD><CODE><CODE>CARD_STAT_SPEED_MIDDLE</CODE></CODE></TD> 142 <TD>8</TD> 143 </TR> 144 <TR> 145<TD><CODE><CODE>CARD_STAT_SPEED_FAST</CODE></CODE></TD> 146 <TD>4</TD> 147 </TR> 148 </TBODY> 149</TABLE> 150<P>If there are fewer than eight frames, set <CODE>CARD_STAT_SPEED_END</CODE> in the icon for the last animation frame. This setting tells the system which frame is the last frame of the animation. Icons must also be in sequential order.</P> 151<P>Another animation option is the repeat pattern. Loop (123412341234...) and bounce (1234321234...) can be selected.</P> 152<P>The above example continues; the following shows how animation operations are handled.</P> 153<BLOCKQUOTE> 154<PRE>frame 0 155long pause 156frame 1 157normal pause 158frame 2 159short pause 160frame 3 161long pause 162frame 0 163. 164. 165.</PRE> 166</BLOCKQUOTE> 167<P>Use the <CODE><a href="CARDSetIconSpeed.html">CARDSetIconSpeed</a></CODE> and <CODE><a href="CARDSetIconAnim.html">CARDSetIconAnim</a></CODE> function to set the following:</P> 168<BLOCKQUOTE> 169<PRE>// icon speeds 170<CODE>CARDSetIconSpeed(stat, 0, CARD_STAT_SPEED_SLOW); 171CARDSetIconSpeed(stat, 1, CARD_STAT_SPEED_MIDDLE); 172CARDSetIconSpeed(stat, 2, CARD_STAT_SPEED_FAST); 173CARDSetIconSpeed(stat, 3, CARD_STAT_SPEED_SLOW); 174CARDSetIconSpeed(stat, 4, CARD_STAT_SPEED_END); 175CARDSetIconAnim(stat, CARD_STAT_ANIM_LOOP);</CODE></PRE> 176</CODE></PRE> 177</BLOCKQUOTE> 178<H2>Storing Settings to the Memory Card</H2> 179<P>Once you have stored all of the icon, banner, and comment information into the <tt>CARDStat</tt> structure, you are ready to store this information to the Memory Card. It is a best practice to save the icon, banner, and comment information to the Memory Card before storing these settings. If the card does not have valid settings, you can assume that the card is broken using this approach. Once you have stored the data to the file (using the <CODE><a href="CARDWrite.html">CARDWrite</a></CODE> function), you can use the <CODE><a href="CARDSetStatus.html">CARDSetStatus</a></CODE> function to store the settings in the <CODE>CARDStat</CODE> structure to the Memory Card system.</P> 180<H2>Comment Strings</H2> 181<P>There are two comment strings that appear on the Revolution system menu. As the API suggests, there is a 32 text character limit for each string. However, note that a proportional font is used on the system menu. Therefore, all 32 text characters may not be displayed. It is important to ensure that the comment text is readable on the system menu.</P> 182<H2>Revision History</H2> 183<P>2006/03/01 Initial version.</P> 184<hr> 185<P>CONFIDENTIAL</p> 186</BODY> 187</HTML>