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="IBM WebSphere Studio Homepage Builder Version 8.0.2.0 for Windows"> 6<meta http-equiv="Content-Style-Type" content="text/css"> 7<link rel="stylesheet" type="text/css" href="CSS/revolution.css"> 8<base target="main"> 9<style type="text/css" media="all"> 10<!-- 11@import url("css/hbm_common.css"); 12h4 { 13 font-size: x-large; 14 border-bottom: 3px double #000; 15} 16PRE 17{ 18 font-family : "Courier New", monospace; 19 font-weight : normal; 20 font-size : 10pt; 21 margin : 0px 20px 10px 30px; 22 padding : 2px 4px 2px 4px; 23 background-color : #eee; 24} 25ul.list { 26 margin:20px 20px; 27} 28ul.list li{ 29 float:left; 30} 31ul.list li a{ 32 color:#060; 33 width: 310px; 34 display:block; 35} 36ul.list li a:active,ul.list li a:hover{ 37 color:#0c0; 38} 39--> 40</style> 41<title>HBM API Introduction</title> 42</head> 43<body> 44<h1>HBM Library Overview</h1> 45<br> <br> 46<h2>HOME Menu</h2> 47<p>To call the HOME Menu, press HOME on the Wii Remote. The HOME Menu must be incorporated into every application. It includes the buttons for shutting down and resetting applications, and displaying and setting information related to the Wii Remote.</p> 48<p>For descriptions of the HOME Menu's functionalities and each of its buttons, refer to the Wii console manual.</p> 49<h2>Special Libraries</h2> 50<p>The <CODE>homebuttonLib.vcmv[D].a</CODE> library included in the RVL directory can be used only with certain channel applications. The <CODE>homebuttonLib.nwm[D].a </CODE> library is for WiiWare. Do not use these two libraries with disc applications.</p> 51<a id="intro" name="intro"></a> 52<h4>Installation</h4> 53<ul class="list"> 54<li><a href="#intro_0">Incorporating into Applications</a> 55<li><a href="#intro_1">HBMCreate() Arguments</a> 56<li><a href="#intro_2">Using Memory Allocator</a> 57<li><a href="#intro_3">Console and Controller Settings</a> 58<li><a href="#intro_4">Simple Pairing With the Wii Remote</a> 59<li><a href="#intro_5">Notes for a KPADRead Value of Zero</a> 60<li><a href="#projection">Projection Matrix Settings During Rendering</a> 61<li><a href="#intro_6">Processing Sound Effects</a> 62<li><a href="#intro_7">Updating Sounds</a> 63<li><a href="#intro_8">Standard Close Process</a> 64<li><a href="#intro_9">Forced Close Process</a> 65<li><a href="#intro_10">Notes for the Stack Size of the Sound Thread</a> 66</ul> 67<br style="clear:both;"> <a id="intro_0" name="intro_0"></a> 68<h2>Incorporating into Applications</h2> 69<p>Link the <CODE>homebuttonLib[D].a</CODE> file and embed the shared resource data contained in the <CODE>dvddata/HomeButton2</CODE> directory into the application's project.</p> 70<p>To start the HOME Menu, call <CODE><A href="hbm_HBMCreate.html">HBMCreate()</A></CODE> then <CODE><A href="hbm_HBMInit.html">HBMInit()</A></CODE> in the application source code, in that order; next, call <CODE><A href="hbm_HBMCalc.html">HBMCalc()</A></CODE> and <CODE><A href="hbm_HBMDraw.html">HBMDraw()</A></CODE> in the main loop.<br>The HOME Menu can be incorporated in one of the following two ways:</p> 71<ul> 72<li>Loading the resources every time, without making it memory-resident.<file:///C:/RVL_SDK/man/ja_JP/hbm/contents.html/li> 73 <ol style="padding-top:10px;"> 74<li>Detect that HOME has been pressed. 75<li>Load a resource with <CODE>HBMCreate()</CODE>. 76<li>Use <CODE>HBMInit()</CODE> to initialize internal library variables. 77<li>Use <CODE>HBMDraw()</CODE> to display the HOME Menu. 78<li>Exit the HOME Menu and then free the resource with <CODE>HBMDelete()</CODE>. 79 <dl> 80<dt style="padding:0px;margin:0px;">To re-display, repeat from step 1. 81 </dl> 82 </ol> 83<li style="padding-top:10px;">By making a resource memory-resident and thereby omitting the resource loading step. 84 <ol style="padding-top:10px;"> 85<li>Load a resource in advance with <CODE>HBMCreate()</CODE> during, for example, game initialization. 86<li>Detect that HOME has been pressed. 87<li>Use <CODE>HBMInit()</CODE> to initialize internal library variables. 88<li>Use <CODE>HBMDraw()</CODE> to display the HOME Menu. 89<li>Exit from HOME Menu. 90 <dl> 91<dt style="padding:0px;margin:0px;">To re-display, repeat from step 2. 92 </dl> 93<li>When the game ends, use <CODE>HBMDelete()</CODE> to free the resources. 94 </ol> 95</ul> 96<p>Note: For details on introducing WiiWare, see the <a href="./wiiware.html">WiiWare Support Guide</a>.</p> 97<a id="intro_1" name="intro_1"></a> 98<h2>HBMCreate() Arguments</h2> 99<p>The following items are passed as arguments to <A href="hbm_HBMCreate.html"><CODE>HBMCreate()</CODE></A>:</p> 100<ul class="index"> 101<li>Layout resource 102<li>Wave archive to be sent to the Wii Remote speaker (required when <CODE>SoundLib</CODE> is not used) 103<li>Message resource 104<li>Setup file data for changing the number of buttons (required for special implementations of the HOME Menu that have a different number of buttons) 105<li>Callback function for sounds 106<li>HOME Menu background flag (Set to zero if the background is translucent when HOME Menu displays; set to 1 if the background is opaque when HOME Menu displays.) 107<li>Region number (specified as <CODE>SC_LANG_????</CODE>) 108<li>Varying interval between frames (set 1.0 for 60 frames) 109<li>16:9 screen aspect ratio 110<li>Work region used by the library and the size of the region 111<li>Pointer to the memory allocator (when prepared by the application) 112</ul> 113<a id="intro_2" name="intro_2"></a> 114<h2>Using Memory Allocator</h2> 115<p>Settings of the <A href="hbm_HBMDataInfo.html"><CODE>HBMDataInfo</CODE> structure</a>, passed to <A href="hbm_HBMCreate.html"><CODE>HBMCreate()</CODE></A>, depend on the type of the HBM library and where the memory allocator is prepared. When <CODE>pAllocator</CODE> is set, it is given priority and used.</p> 116<a id="intro_3" name="intro_3"></a> 117<h2>Console and Controller Settings</h2> 118<p>The following settings can be configured using the HOME Menu:</p> 119<ul class="index"> 120<li>Controller volume setting 121<li>Controller Rumble feature setting 122</ul> 123<p>These items, which must be set on the console or controller, are saved when you exit the HOME Menu.</p> 124<a id="intro_4" name="intro_4"></a> 125<h2>Simple Pairing With the Wii Remote</h2> 126<p><font color="red">The application should suspend simple pairing with the Wii Remote before processing the HOME Menu. </font>To be safe, however, simple pairing is terminated by executing <CODE>WPADStopSimpleSync</CODE> in the <A href="hbm_HBMInit.html"><CODE>HBMInit</CODE></a> function. If desired, resume pairing processing after exiting the HOME Menu.</p> 127<a id="intro_5" name="intro_5"></a> 128<h2>Notes for a KPADRead Value of Zero</h2> 129<p>When <CODE>KPADRead</CODE> returns zero, the value of <CODE>KPADStatus</CODE> is undefined. If this value is used unchanged and <CODE>HBMUpdate</CODE> is run, improper behavior may result. When <CODE>KPADRead</CODE> returns zero, zero-clear the <CODE>KPADStatus</CODE> buffer.</p> 130<a id="projection" name="projection"></a> 131<h2>Projection Matrix Settings During Rendering</h2> 132<p>Before rendering the HOME Menu with <CODE>HBMDraw</CODE>, a designated projection matrix must be passed to GX using the <CODE>GXSetProjection</CODE> function. Although the projection matrix will change based on the extent of expansion in VI, the following examples show how to create projection matrices with arbitrary VI settings that will display the same as the sample.<br> <br> 133</p> 134<p>For 4:3 Settings:</p> 135<pre><code>f32 viRateX = viWidth / 670.f; 136f32 viRateY = viHeight / 456.f; 137MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 304.0f, viRateX * 304.0f, 0.0f, 500.0f); 138</code></pre> 139<p>For 16:9 Settings:</p> 140<pre><code>f32 viRateX = viWidth / 686.f; 141f32 viRateY = viHeight / 456.f; 142MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 416.0.0f, viRateX * 416.0.0f, 0.0f, 500.0f); 143</code></pre> 144<p> </p> 145<a id="intro_6" name="intro_6"></a> 146<h2>Processing Sound Effects</h2> 147<p>When leaving sound effect (SE) processing to the library, initialize sounds by calling the <CODE><A href="hbm_HBMCreateSound.html">HBMCreateSound()</A></CODE> function after <CODE><A href="hbm_HBMCreate.html">HBMCreate()</A></CODE>, and then call <CODE><A href="hbm_HBMUpdateSound.html">HBMUpdateSound()</A></CODE> at each frame.</p> 148<p>To carry out sound effect processing in the application, set a callback function in the <CODE>sound_callback</CODE> member of the <CODE><A href="hbm_HBMDataInfo.html">HBMDataInfo</CODE> structure</a> without calling the <CODE>HBMCreateSound()</CODE> function. Because the callback function will be called from the library whenever SE are played, perform any necessary processing there. Sound callback functions may also be called by events other than those playing sound effects. From the value passed by <B><I><CODE>evt</CODE></I></B>, identify the event type according to the <A href="hbm_HBMSEV_XXX.html"><CODE>HBMSEV_XXX</CODE> enumerator</a>; then have the application perform suitable processing.</p> 149<p>Sound generation for the Wii remote speaker is always performed in the HBM Library; the application side does not need to be aware of its operation.<BR>The sound data (<CODE>SpeakerSe.arc</CODE>, provided as a shared resource data), which is set to the <SPAN class="argument"><CODE>spkSeBuf</CODE></SPAN> member of the <A href="hbm_HBMDataInfo.html"><CODE>HBMDataInfo</CODE> structure</a>, is played when the volume is raised or lowered and when the Wii Remote is connected at pairing. (Depending on the state of surrounding networks and on the system processing load, it may not play properly from the Wii Remote speakers. However, because this is in the specification, applications do not need to enact countermeasures.)</p> 150<a id="intro_7" name="intro_7"></a> 151<h2>Updating Sounds</h2> 152<p>Sound effect updates and Wii Remote updates are performed by <a href="hbm_HBMUpdateSound.html"><CODE>HBMUpdateSound</CODE></a>. When updates are performed by the program component on its own behalf, it is not necessary to call <CODE>HBMUpdateSound</CODE>.</p> 153<a id="intro_8" name="intro_8"></a> 154<h2>Standard Close Process</h2> 155<p>To obtain the number of the button pressed to exit the HOME Menu, use <CODE><A href="hbm_HBMGetSelectBtnNum.html">HBMGetSelectBtnNum()</A></CODE>. Have your application perform the required processing that corresponds to that button number (for example, return to the system menu, reset, and so on).</p> 156<p>When HOME is pressed (or <B>Close</B> is clicked) to exit the HOME Menu, <A href="hbm_HBMGetSelectBtnNum.html"><CODE>HBMGetSelectBtnNum()</CODE></A> returns <<I>button number</I>> + 1. When the HOME Menu is running, <CODE><A href="hbm_HBMGetSelectBtnNum.html">HBMGetSelectBtnNum()</A></CODE> returns –1.</p> 157<p>To call the HOME Menu again after exiting, call <CODE><A href="hbm_HBMInit.html">HBMInit()</A></CODE>.</p> 158<a id="intro_9" name="intro_9"></a> 159<h2>Forced Close Process</h2> 160<p>If RESET or Power Button on the Wii console is pressed while the HOME Menu is open, call <CODE><A href="hbm_HBMGetSelectBtnNum.html">HBMStartBlackOut()</A></CODE> to force-close the HOME Menu.</p> 161<p>Note that the status after a forced reset is the same as after closing the HOME Menu by pressing RESET (the <CODE><A href="hbm_HBMGetSelectBtnNum.html">HBMGetSelectBtnNum()</A></CODE> return value is <CODE>HBM_SELECT_BTN2</CODE>).</p> 162<a id="intro_10" name="intro_10"></a> 163<h2>Notes for the Stack Size of the Sound Thread</h2> 164<p>Use the <A href="hbm_HBMCreateSound.html"><CODE>HBMCreateSound</A></CODE></A> function to create a sound thread in the HBM library. The stack size is 16 KB.</p> 165<p>The current thread's stack is also used within interrupt handlers on Wii. As a result, the HMB library's sound thread stack may prove to be insufficient.</p> 166<p><b><font color="red">If execution halts due to an insufficient stack size, increase the value of <CODE>HBM_SND_THREAD_STACK_SIZE</CODE> by defining it before including <CODE>hbm.h</CODE>.</font></b><br> 167</p> 168<br> <br> <a id="mount" name="mount"></a> 169<h4><a name="inout">Typical Implementation for Entering and Leaving HOME Menu </a></h4> 170<ul class="list"> 171<li><a href="#inout_0">When Entering the HOME Menu</a> 172<li><a href="#inout_1">HBMCreate() Arguments</a> 173</ul> 174<br style="clear:both;"> <a id="inout_0" name="inout_0"></a> 175<h2>When Entering the HOME Menu</h2> 176<ul> 177<li>Functions that should be called before entering the HOME Menu 178</ul> 179<pre><code>// Set floating point/integer fast cast feature 180OSInitFastCast(void); 181</code></pre> 182<p>This is used by the HBM library for the drawing process.<br>If this function is not called, display of the HOME Menu will be distorted.<br>Call it once at the start of the application.<br> 183</p> 184<ul> 185<li>GX functions that have an effect on the HOME Menu 186</ul> 187<pre><code>// Whether or not to allow updates to the color buffer 188GXSetColorUpdate(GX_TRUE); 189</code></pre> 190<pre><code>// Clipping functions 191GXSetScissor( *1 ); 192GXSetScissorBoxOffset( *1 ); 193</code></pre> 194<pre><code>// Viewport 195GXSetViewport( *1 ); 196// Other viewport-related functions 197</code></pre> 198<pre><code>// Projection 199GXSetProjection( *1 ); 200// Other projection-related functions 201</code></pre> 202<pre><code>// Frame buffer-related functions 203GXSetCopyFilter( *2 ); 204GXSetDispCopyDst( *1 ); 205GXSetDispCopySrc( *1 ); 206// Other frame buffer-related functions 207</code></pre> 208<p>For these functions, set values on the application side before starting the HOME Menu.<br>After the HOME Menu has completed, reconfigure the values on the application side as needed.<br> <br> *1 For these functions' arguments, substitute items appropriate to the application. <br>*2 For this function's arguments, substitute application-appropriate items to items other than antialiasing. Turn antialiasing off.</p> 209<ul> 210<li>Wii Remote Processing 211</ul> 212<p>Do not perform simple pairing while in the HOME Menu. Halt it before starting the HOME Menu.<br>However, to be safe, <CODE>WPADStopSimpleSync</CODE> is called within <A href="hbm_HBMInit.html"><CODE>HBMInit</CODE></a> to stop processing.<br>Resume simple pairing in the application after exiting from the HOME Menu, if desired.</p> 213<ul> 214<li>Shared sound processing 215</ul> 216<p>Have the application set the sound volume to zero. Use 300 ms for the fade time.</p> 217<ul> 218<li>When an Application Uses NintendoWare 219</ul> 220<pre><code>static void nw4r::snd::SoundSystem::ClearEffect(nw4r::snd::AuxBus bus, int fadeTime);</code></pre> 221<p>Use this code to shut down all effects <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE>. Use 250 ms for the fade time.</p> 222<ul> 223<li>When an Application Does Not Use NintendoWare 224</ul> 225<pre><code>// Fade process 226AXGetAux?ReturnVolume() // ?=A,B,C 227AXSetAux?ReturnVolume() // ?=A,B,C 228</code></pre> 229<pre><code>// Shutdown 230AXFXReverbHiShutdown() // When ReverbHi 231</code></pre> 232<p>Use functions such as these to fade out all the effects <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE>, then shut them down. Use 250 ms for the fade time.</p> 233<p class="warning"><B>Note:</B> Effect fade-outs should end while the sound is still fading. The sound completely fades out in 300 ms.</p> 234<p class="warning"><B>Note: </B>Do not use functions such as <CODE>AXFXReverbHiSettings()</CODE> that internally change parameters, including shutdown. Noise will be generated if these functions are used to change output values during a fade.</p> 235<a id="inout_1" name="inout_1"></a> 236<h2>When Leaving the HOME Menu</h2> 237<ul> 238<li>GX functions, which are called internally by the HOME button 239</ul> 240<pre><code>// Alpha compare TEV settings<br>GXSetAlphaCompare( GX_ALWAYS,0, GX_AOP_OR, GX_ALWAYS, 0 );</code></pre> 241<pre><code>// Z-compare mode settings<br>GXSetZMode(GX_DISABLE, GX_ALWAYS, GX_DISABLE);</code></pre> 242<pre><code>// Settings for the number of indirect lookups to use<br>GXSetNumIndStages(0);</code></pre> 243<pre><code>// TEV swap table settings<br>GXSetTevSwapModeTable(GX_TEV_SWAP_0, GX_CH_RED, GX_CH_GREEN, GX_CH_BLUE, GX_CH_ALPHA);</code></pre> 244<pre><code>// Settings for the swap mode for swapping to a given TEV stage<br>GXSetTevSwapMode(GX_TEVSTAGE0, GX_TEV_SWAP0, GX_TEV_SWAP0);</code></pre> 245<pre><code>// Culling control<br>GXSetCullMode(GX_CULL_NONE);</code></pre> 246<pre><code>// Gamma correction for pixels being copied from EFB to XFB<br>GXSetDispCopyGamma(GX_GM_1_0);</code></pre> 247<p>For these functions, the settings of the application will be overwritten during execution of the HOME Menu. They should be reset as necessary when closing the HOME Menu.<br><B>Note:</B> Values in parentheses are the actual values set internally by the HOME button.</p> 248<ul> 249<li>Sound Processing 250</ul> 251<p>Be sure to restore the sound volume on the application side. Allocate 300 ms or more for the fade time.</p> 252<p>Initialize effects <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE> on the application side. Also:</p> 253<pre><code>AXSetAux?ReturnVolume() // ?=A,B,C</code></pre> 254<p>Use this code to restore the output on <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE> (no need to apply fade).</p> 255<p>The above does not necessarily apply when leaving the HOME Menu by clicking Wii Menu or Reset.</p> 256<ul> 257<li>Wii Remote Processing 258</ul> 259<p>Simple pairing for the Wii Remote is suspended if it is active when the HOME Menu is executed.<br>Resume simple pairing in the application, if desired. <br><br>In addition, the status returned for the Wii Remote speaker is unstable. Since the HOME Menu uses the Wii Remote speaker, set the speaker's state to <CODE>WPAD_SPEAKER_OFF</CODE> on completion if it is not used. 260</p> 261<br> <br> 262<h2>Revision History</h2> 263<dl class="history"> 264 <dt>2008/02/07 265<dd>Added Wii Remote processing information when leaving the HOME Menu. 266 <dt>2008/02/01 267<dd>Added text about the use of WiiWare to the sections "Special Libraries" and "Incorporating into Applications". 268 <dt>2007/11/26 269<dd>Added "Simple Pairing with the Wii Remote", "Notes for a KPADRead Value of Zero", and "Projection Matrix Settings During Rendering". 270<dd>Revised notes related to the sound thread's stack size and the resumption of simple pairing. 271 <dt>2007/09/28 272<dd>Added cautions related to the stack size of the sound thread and restarting of simple pairing. 273 <dt>2007/09/03 274<dd>Added precautions related to the sound fade-out time. Removed the item related to sound customization. 275 <dt>2007/05/09 276<dd>Revised the description for the SDK version. 277 <dt>2007/04/12 278<dd>Added information to "Incorporating into Applications". 279<dd>Added the values that are set "When Leaving the HOME Menu". 280 <dt>2007/01/30 281<dd>Revised "Typical Implementation for Entering and Leaving the HOME Menu". 282<dd>Revised page layout. 283 <dt>2006/12/18 284<dd>Revised "Processing Sound Effects". 285 <dt>2006/11/11 286<dd>Added information to "Incorporating into Applications". 287<dd>Deleted information about manual viewer and added a section about special libraries. 288 <dt>2006/10/19 289<dd>Manual edition (added "Displaying the Manual from the HOME Menu"). 290 <dt>2006/10/02 291<dd>Initial version. 292</dl> 293<HR> 294<P>RVL-06-0172-001-R<br>CONFIDENTIAL</P> 295</BODY> 296</HTML>