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 Function Arguments</a> 56 <li><a href="#intro_2">Using Memory Allocator</a> 57 <li><a href="#intro_3">Console and Wii Remote 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="#intro_4_1">With No Support for Classic Controllers</a> 61 <li><a href="#projection">Projection Matrix Settings During Rendering</a> 62 <li><a href="#intro_6">Processing Sound Effects</a> 63 <li><a href="#intro_7">Updating Sounds</a> 64 <li><a href="#intro_8">Standard Close Process</a> 65 <li><a href="#intro_9">Forced Close Process</a> 66 <li><a href="#intro_10">Notes for the Stack Size of the Sound Thread</a> 67</ul> 68<br style="clear:both;"> <a id="intro_0" name="intro_0"></a> 69<h2>Incorporating into Applications</h2> 70<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> 71<p>To start the HOME Menu, call <A href="hbm_HBMCreate.html"><CODE>HBMCreate</CODE></A> then <A href="hbm_HBMInit.html"><CODE>HBMInit</CODE></A> in the application source code, in that order; next, call <A href="hbm_HBMCalc.html"><CODE>HBMCalc</CODE></A> and <A href="hbm_HBMDraw.html"><CODE>HBMDraw</CODE></A> in the main loop.<br>The HOME Menu can be incorporated in one of the following two ways:</p> 72<ul> 73 <li>Loading the resources every time, without making it memory-resident.<file:///C:/RVL_SDK/man/ja_JP/hbm/contents.html/li> 74 <ol style="padding-top:10px;"> 75 <li>Detect that HOME has been pressed. 76 <li>Load a resource with <CODE>HBMCreate</CODE>. 77 <li>Use the <CODE>HBMInit</CODE> function to initialize internal library variables. 78 <li>Use the <CODE>HBMDraw</CODE> function to display the HOME Menu. 79 <li>Exit the HOME Menu and then free the resource with <CODE>HBMDelete</CODE>. 80 <dl> 81 <dt style="padding:0px;margin:0px;">To re-display, repeat from step 1. 82 </dl> 83 </ol> 84 <li style="padding-top:10px;">By making a resource memory-resident and thereby omitting the resource loading step. 85 <ol style="padding-top:10px;"> 86 <li>Load a resource in advance with <CODE>HBMCreate</CODE> during, for example, game initialization. 87 <li>Detect that HOME has been pressed. 88 <li>Use the <CODE>HBMInit</CODE> function to initialize internal library variables. 89 <li>Use the <CODE>HBMDraw</CODE> function to display the HOME Menu. 90 <li>Exit from HOME Menu. 91 <dl> 92 <dt style="padding:0px;margin:0px;">To re-display, repeat from step 2. 93 </dl> 94 <li>When the game ends, use the <CODE>HBMDelete</CODE> function to free the resources. 95 </ol> 96</ul> 97<p>Note: For details on introducing WiiWare, see the <a href="./wiiware.html">WiiWare Support Guide</a>.</p> 98<a id="intro_1" name="intro_1"></a> 99<h2>HBMCreate Function Arguments</h2> 100<p>The following items are passed as arguments to <A href="hbm_HBMCreate.html"><CODE>HBMCreate</CODE></A>.</p> 101<ul class="index"> 102 <li>Layout resource 103 <li>Wave archive to be sent to the Wii Remote speaker (required when <CODE>SoundLib</CODE> is not used) 104 <li>Message resource 105 <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) 106 <li>Callback function for sounds 107 <li>HOME Menu background flag (set to zero if the background is translucent when HOME Menu is displayed; set to 1 if the background is opaque when HOME Menu is displayed) 108 <li>Region number (specify as <CODE>SC_LANG_????</CODE>) 109 <li>Varying interval between frames (set 1.0 for 60 frames) 110 <li>16:9 screen aspect ratio 111 <li>Work region used by the library and the size of the region 112 <li>Pointer to the memory allocator (when prepared by the application) 113</ul> 114<a id="intro_2" name="intro_2"></a> 115<h2>Using Memory Allocator</h2> 116<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> 117<a id="intro_3" name="intro_3"></a> 118<h2>Console and Wii Remote Settings</h2> 119<p>The following settings can be configured using the HOME Menu:</p> 120<ul class="index"> 121 <li>Wii Remote Volume Setting 122 <li>Wii Remote Rumble Setting 123</ul> 124<p>These items, which must be set on the console or Wii Remote, are saved when you exit the HOME Menu.</p> 125<a id="intro_4" name="intro_4"></a> 126<h2>Simple Pairing with the Wii Remote</h2> 127<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> 128<a id="intro_5" name="intro_5"></a> 129<h2>Notes for a KPADRead Value of Zero</h2> 130<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 the return value of <CODE>KPADRead</CODE> is 0, pass the last normal value obtained in <CODE>KPADStatus</CODE>.</p> 131<p> 132<font color="red"><B>Note:</B> This method of handling is not needed when using Revolution SDK 3.2 or later.</font> 133</p> 134 135<a id="intro_4_1" name="intro_4_1"></a> 136<h2>With No Support for Classic Controllers</h2> 137<p> 138If you want to disable Classic Controller values even on the HOME Button Menu for software that does not support Classic Controllers, set <CODE>use_devtype</CODE> of the <a href="hbm_HBMControllerData.html">HBMControllerData structure</a> to <CODE>WPAD_DEV_CORE</CODE> when the device type obtained by <CODE>WPADProbe</CODE> is <CODE>WPAD_DEV_CLASSIC</CODE>. 139</p> 140 141<a id="projection" name="projection"></a> 142<h2>Projection Matrix Settings During Rendering</h2> 143<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> 144</p> 145<p>For 4:3 Settings:</p> 146<pre><code>f32 viRateX = viWidth / 670.f; 147f32 viRateY = viHeight / 456.f; 148MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 304.0f, viRateX * 304.0f, 0.0f, 500.0f); 149</code></pre> 150<p>For 16:9 Settings:</p> 151<pre><code>f32 viRateX = viWidth / 686.f; 152f32 viRateY = viHeight / 456.f; 153MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 416.0.0f, viRateX * 416.0.0f, 0.0f, 500.0f); 154</code></pre> 155<p> </p> 156<a id="intro_6" name="intro_6"></a> 157<h2>Processing Sound Effects</h2> 158<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> 159<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> 160<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> 161<a id="intro_7" name="intro_7"></a> 162<h2>Updating Sounds</h2> 163<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> 164<a id="intro_8" name="intro_8"></a> 165<h2>Standard Close Process</h2> 166<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 (return to the system menu, reset, and so on).</p> 167<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> 168<p>To call the HOME Menu again after exiting, call <CODE><A href="hbm_HBMInit.html">HBMInit</A></CODE>.</p> 169<a id="intro_9" name="intro_9"></a> 170<h2>Forced Close Process</h2> 171<p>If the RESET or Power Button on the Wii console is pressed while the HOME Menu is open, call the <A href="hbm_HBMGetSelectBtnNum.html"><CODE>HBMStartBlackOut</CODE></A> function to close the HOME Menu. 172</p> 173<p>Note that the status after a forced reset is the same as after closing the HOME Menu by pressing RESET (the <A href="hbm_HBMGetSelectBtnNum.html"><CODE>HBMGetSelectBtnNum</CODE></A> return value is <CODE>HBM_SELECT_BTN2</CODE>).</p> 174<a id="intro_10" name="intro_10"></a> 175<h2>Notes for the Stack Size of the Sound Thread</h2> 176<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> 177<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> 178<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> 179</p> 180<br> <br> <a id="mount" name="mount"></a> 181<h4><a name="inout">Typical Implementation for Entering and Leaving HOME Menu </a></h4> 182<ul class="list"> 183 <li><a href="#inout_0">When Entering the HOME Menu</a> 184 <li><a href="#inout_1">HBMCreate Function Arguments</a> 185</ul> 186<br style="clear:both;"> <br> <a id="inout_0" name="inout_0"></a> 187<h2>When Entering the HOME Menu</h2> 188<ul> 189 <li>Functions that should be called before entering the HOME Menu 190</ul> 191<pre><code>// Set floating point/integer fast cast feature 192OSInitFastCast(void); 193</code></pre> 194<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> 195</p> 196<ul> 197 <li>GX functions that have an effect on the HOME Menu 198</ul> 199<pre><code>// Whether or not to allow updates to the color buffer 200GXSetColorUpdate(GX_TRUE); 201</code></pre> 202<pre><code>// Clipping functions 203GXSetScissor( *1 ); 204GXSetScissorBoxOffset( *1 ); 205</code></pre> 206<pre><code>// Viewport 207GXSetViewport( *1 ); 208// Other viewport-related functions 209</code></pre> 210<pre><code>// Projection 211GXSetProjection( *1 ); 212// Other projection-related functions 213</code></pre> 214<pre><code>// Frame buffer-related functions 215GXSetCopyFilter( *2 ); 216GXSetDispCopyDst( *1 ); 217GXSetDispCopySrc( *1 ); 218// Other frame buffer-related functions 219</code></pre> 220<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> 221<ul> 222 <li>Wii Remote Processing 223</ul> 224<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> 225<ul> 226 <li>Shared sound processing 227</ul> 228<p>Have the application set the sound volume to zero. Use 300 ms for the fade time.</p> 229<ul> 230 <li>When an Application Uses NintendoWare 231</ul> 232<pre><code>static void nw4r::snd::SoundSystem::ClearEffect(nw4r::snd::AuxBus bus, int fadeTime);</code></pre> 233<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> 234<ul> 235 <li>When an Application Does Not Use NintendoWare 236</ul> 237<pre><code>// Fade process 238AXGetAux?ReturnVolume() // ?=A,B,C 239AXSetAux?ReturnVolume() // ?=A,B,C 240</code></pre> 241<pre><code>// Shutdown 242AXFXReverbHiShutdown() // When ReverbHi 243</code></pre> 244<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> 245<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> 246<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> 247<a id="inout_1" name="inout_1"></a> 248<h2>When Leaving the HOME Menu</h2> 249<ul> 250 <li>GX functions, which are called internally by the HOME button 251</ul> 252<pre><code>// Alpha compare TEV settings<br>GXSetAlphaCompare( GX_ALWAYS,0, GX_AOP_OR, GX_ALWAYS, 0 );</code></pre> 253<pre><code>// Z-compare mode settings<br>GXSetZMode(GX_DISABLE, GX_ALWAYS, GX_DISABLE);</code></pre> 254<pre><code>// Settings for the number of indirect lookups to use<br>GXSetNumIndStages(0);</code></pre> 255<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> 256<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> 257<pre><code>// Culling control<br>GXSetCullMode(GX_CULL_NONE);</code></pre> 258<pre><code>// Gamma correction for pixels being copied from EFB to XFB<br>GXSetDispCopyGamma(GX_GM_1_0);</code></pre> 259<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> 260<ul> 261 <li>Sound Processing 262</ul> 263<p>Be sure to restore the sound volume on the application side. Allocate 300 ms or more for the fade time.</p> 264<p>Initialize effects <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE> on the application side. Also:</p> 265<pre><code>AXSetAux?ReturnVolume() // ?=A,B,C</code></pre> 266<p>Use this code to restore the output on <CODE>AUX_A</CODE> through <CODE>AUX_C</CODE> (no need to apply fade).</p> 267<p>The above does not necessarily apply when leaving the HOME Menu by clicking Wii Menu or Reset.</p> 268<ul> 269 <li>Wii Remote Processing 270</ul> 271<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. 272</p> 273<br> <br> 274<h2>Revision History</h2> 275<dl class="history"> 276 <dt>2008/09/24 277 <dd>Revised <B>Notes for a KPADRead Value of Zero</B>. 278 <dd>Added <B>With No Support for Classic Controllers</B>. 279 <dd>Revised terminology. 280 <dt>2008/02/07 281 <dd>Added Wii Remote processing information when leaving the HOME Menu. 282 <dt>2008/02/01 283 <dd>Added text about the use of WiiWare to <B>Special Libraries</B> and <B>Incorporating into Applications</B>. 284 <dt>2007/11/26 285 <dd>Added <B>Simple Pairing with the Wii Remote</B>, <B>Notes for a KPADRead Value of Zero</B>, and <B>Projection Matrix Settings During Rendering</B>. 286 <dd>Revised notes related to the sound thread's stack size and the resumption of simple pairing. 287 <dt>2007/09/28 288 <dd>Added cautions related to the stack size of the sound thread and restarting of simple pairing. 289 <dt>2007/09/03 290 <dd>Added precautions related to the sound fade-out time. Removed the item related to sound customization. 291 <dt>2007/05/09 292 <dd>Revised the description for the SDK version. 293 <dt>2007/04/12 294 <dd>Added information to <B>Incorporating into Applications</B>. 295 <dd>Added the values that are set to <B>When Leaving the HOME Menu</B>. 296 <dt>2007/01/30 297 <dd>Revised <B>Typical Implementation for Entering and Leaving the HOME Menu</B>. 298 <dd>Revised page layout. 299 <dt>2006/12/18 300 <dd>Revised <B>Processing Sound Effects</B>. 301 <dt>2006/11/11 302 <dd>Added information to <B>Incorporating into Applications</B>. 303 <dd>Deleted information about manual viewer and added a section about special libraries. 304 <dt>2006/10/19 305 <dd>Manual edition (added <B>Displaying the Manual from the HOME Menu</B>). 306 <dt>2006/10/02 307 <dd>Initial version. 308</dl> 309<HR> 310<P>RVL-06-0172-001-S<br>CONFIDENTIAL</P> 311</BODY> 312</HTML>