en_US/hbm/intro.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 8.0.2.0 for Windows">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" type="text/css" href="CSS/revolution.css">
<base target="main">
<style type="text/css" media="all">
<!--
@import url("css/hbm_common.css");
h4 {
  font-size: x-large;
  border-bottom: 3px double #000;
}
PRE
{
  font-family			: "Courier New", monospace;
  font-weight			: normal;
  font-size			: 10pt;
  margin				: 0px 20px 10px 30px;
  padding				: 2px 4px 2px 4px;
  background-color	: #eee;
}
h5 {
	clear:both;
  margin:10px 0px 10px 15px;
}
ul.list {
  margin:0px 0px 20px 0px;
}
ul.list li{
  float:left;
  width: 330px;
}
ul.list li a{
  color:#060;
}
ul.list li a:active,ul.list li a:hover{
  color:#0c0;
}
-->
</style>
<title>HBM API Introduction</title>
</head>
<body>
<h1>HBM Library Overview</h1>
<br> <br>
<h2>HOME Menu</h2>

<p>To call the HOME Menu, press HOME on the Wii Remote. <font color="red">The HOME Menu must be incorporated into every application. </font><br>It includes the buttons for shutting down and resetting applications, and for displaying and setting information related to the Wii Remote.</p>
<p>For descriptions of the HOME Menu's functionalities and each of its buttons, see the <I>Wii Operations Manual</I>.<br /><font color="red">Chapter 11 of the <I>Wii Programming Guidelines</I> addresses the HOME Menu. Read this chapter of the Guidelines before implementing the HOME Menu.</font></p>
<p><font color="red"><b>Note:<br />Currently, using the library as an RSO leads to the following kinds of bugs.<br />Callback process is called after <CODE>HBMDelete</CODE>. Using the HOME Menu from an RSO causes memory to be accessed after unlinking.<br />When deleting the library from memory, after running <CODE>HBMDelete</CODE> on the application side, check that the return value of running the <CODE>WPADProbe</CODE> function against the connected Wii Remote channel is not <CODE>WPAD_ERR_BUSY</CODE>, and then deallocate the RSO or memory.</b></font></p>
<h2>Types of Applications and Libraries Used </h2>
<p>
Applications use the following libraries.
</p>
<TABLE class="table" style="margin-top:15px;">
  <TBODY>
    <TR>
<TH class="category" width="190" style="text-align:center;">Application Types</TH>
<TH class="category" width="190" style="text-align:center;">Library Used </TH>
    </TR>
    <TR>
<TD style="text-align:center;">Disc Applications</TD>
<TD style="text-align:center;"><CODE>homebuttonLib[D].a</CODE> </TD>
    </TR>
    <TR>
<TD style="text-align:center;">WiiWare Applications </TD>
<TD style="text-align:center;"><CODE>homebuttonLib.nwm[D].a</CODE> </TD>
    </TR>
  </TBODY>
</TABLE>
<p>
<B>Note:</B> The <CODE>homebuttonLib.vcmv[D].a</CODE> file is a library that can be used only with certain channel applications. Do not use this for ordinary applications.</p>

<a id="intro" name="intro"></a>
<h4>Installation</h4>
<h5>Initialization</h5>
<ul class="list">
<li><a href="#intro_0">Incorporating Into Applications</a>
<li><a href="#intro_1">The <SPAN class="argument">HBMDataInfo</SPAN> Argument of the <CODE>HBMCreate</CODE> Function </a>
<li style=" clear:both;"><a href="#intro_2">Using Memory Allocator</a>
<li><a href="#intro_2_1">Notes When Using the <CODE>HBMCreateSound</CODE> Function </a>
</ul>
<h5>Wii Remote</h5>
<ul class="list">
<li><a href="#intro_3">Console and Wii Remote Settings</a>
<li><a href="#intro_4">Simple Pairing with the Wii Remote</a>
<li style=" clear:both;"><a href="#intro_5">Notes for a KPADRead Value of Zero</a>
<li><a href="#intro_4_1">With No Support for Classic Controllers</a>
</ul>
<h5>Rendering</h5>
<ul class="list">
<li><a href="#intro_2_2">Making the HOME Menu Background Translucent </a>
<li><a href="#projection">Projection Matrix Settings During Rendering</a>
</ul>
<h5>Sound</h5>
<ul class="list">
<li><a href="#intro_6">Processing Sound Effects</a>
<li><a href="#intro_7">Updating Sounds</a>
<li style=" clear:both;"><a href="#intro_10">Notes for the Stack Size of the Sound Thread</a>
</ul>
<h5>End</h5>
<ul class="list">
<li><a href="#intro_8">Standard Close Process</a>
<li><a href="#intro_9">Forced Close Process</a>
</ul>
<br style="clear:both;"> <a id="intro_0" name="intro_0"></a>
<h2>Incorporating Into Applications</h2>
<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>
<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 several ways:
</p>
<ul>
<li>How to create an instance every time that is not memory-resident
  <ol style="padding-top:10px;">
<li>Detect that HOME has been pressed.
<li>Create an instance with the <CODE>HBMCreate</CODE> function.
<li>Create a sound instance with the <CODE>HBMCreateSound</CODE> function.
<li>Use the <CODE>HBMInit</CODE> function to initialize internal library variables.
<li>Use the <CODE>HBMDraw</CODE> function to display the HOME Menu.
<li>Exit the HOME Menu and then release the instances with the <CODE>HBMDeleteSound</CODE> and <CODE>HBMDelete</CODE> functions.
    <dl>
<dt style="padding:0px;margin:0px;">To re-display, repeat from step 1.
    </dl>
  </ol>
<li style="padding-top:10px;">How to keep resources resident in memory and omit the loading and instance creation steps
  <ol style="padding-top:10px;">
<li>Create instances with the <CODE>HBMCreate</CODE> and <CODE>HBMCreateSound</CODE> functions during, for example, game initialization.
<li>Detect that HOME has been pressed.
<li>Use the <CODE>HBMInit</CODE> function to initialize internal library variables.
<li>Use the <CODE>HBMDraw</CODE> function to display the HOME Menu.
<li>Exit from HOME Menu.
    <dl>
<dt style="padding:0px;margin:0px;">To re-display, repeat from step 2.
    </dl>
<li>When the game ends, use the <CODE>HBMDelete</CODE> and <CODE>HBMDeleteSound</CODE> functions to release the instances.
  </ol>
<li style="padding-top:10px;">How to create just a sound instance
  <dl>
<dt style="padding:0px;margin:0px;">(Clearing out a sound instance allows you to deallocate sound resources. Use this approach when you want to take the middle road between the two approaches above, for memory or start-up speed reasons.)
  </dl>
  <ol style="padding-top:10px;">
<li>Create instances with the <CODE>HBMCreate</CODE> function during, for example, game initialization.
<li>Detect that HOME has been pressed.
<li>Create a sound instance with the <CODE>HBMCreateSound</CODE> function.
<li>Use the <CODE>HBMInit</CODE> function to initialize internal library variables.
<li>Use the <CODE>HBMDraw</CODE> function to display the HOME Menu.
<li>Exit from the HOME Menu.
<li>Release the sound instance using the <CODE>HBMDeleteSound</CODE> function.
    <dl>
<dt style="padding:0px;margin:0px;">To re-display, return to step ２.
    </dl>
<li>When the game ends, use the <CODE>HBMDelete</CODE> function to release the instance.
  </ol>
</ul>
<p>Note: For details on introducing WiiWare, see the <a href="./wiiware.html">WiiWare Support Guide</a>.</p>
<a id="intro_1" name="intro_1"></a>
<h2>The HBMDataInfo Argument of the HBMCreate Function </h2>
<p>The following items are passed to the <CODE>HBMCreate</CODE> function's argument, <a href="hbm_HBMDataInfo.html"><SPAN class="argument">HBMDataInfo</SPAN></a>:<br /><font color="red"><B>Note:</B> <SPAN class="argument">HBMDataInfo</SPAN> must be retained until the <a style="color:#f00;" href="hbm_HBMDelete.html"><CODE>HBMDelete</CODE></a> function is called.</font></p>
<ul class="index">
<li><SPAN class="argument">layoutBuf</SPAN>: Passes the address where the layout resource file was loaded. For disc applications, use the 2-button file (<CODE>HomeButton2</CODE>).
  <table class="table" style="margin-top:15px;">
    <TR>
      <TH class="category" width="140"></TH>
<TH class="category" width="180">Japan</TH>
<TH class="category" width="180">English</TH>
<TH class="category" width="180">German</TH>
<TH class="category" width="180">French</TH>
<TH class="category" width="180">Spanish</TH>
    </TR>
    <TR>
<TH class="category" style="text-align:center;">Disc</TD>
<TD style="text-align:center;">homeBtn.arc</TD>
<TD style="text-align:center;">homeBtn_ENG.arc</TD>
<TD style="text-align:center;">homeBtn_GER.arc</TD>
<TD style="text-align:center;">homeBtn_FRA.arc</TD>
<TD style="text-align:center;">homeBtn_SPA.arc</TD>
    </TR>
    <TR>
<TH class="category" style="text-align:center;">WiiWare</TD>
<TD style="text-align:center;">LZ77_homeBtn.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_ENG.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_GER.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_FRA.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_SPA.arc</TD>
    </TR>
    <TR>
      <TH class="category"></TH>
<TH class="category" width="180">Italian</TH>
<TH class="category" width="180">Dutch</TH>
<TH class="category" width="180">Chinese</TH>
<TH class="category" width="180">Korean</TH>
     </TR>
    <TR>
<TH class="category" style="text-align:center;">Disc</TD>
<TD style="text-align:center;">homeBtn_ITA.arc</TD>
<TD style="text-align:center;">homeBtn_NED.arc</TD>
<TD style="text-align:center;">homeBtn_CHN.arc</TD>
<TD style="text-align:center;">homeBtn_KOR.arc</TD>
    </TR>
    <TR>
<TH class="category" style="text-align:center;">WiiWare</TD>
<TD style="text-align:center;">LZ77_homeBtn_ITA.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_NED.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_CHN.arc</TD>
<TD style="text-align:center;">LZ77_homeBtn_KOR.arc</TD>
    </TR>
  </table>
<li><SPAN class="argument">spkSeBuf</SPAN>: Passes the address where the waveform archive file to send to the Wii Remote speaker was loaded. Disc applications load <CODE>SpeakerSe.arc</CODE> and WiiWare applications load <CODE>Huf8_SpeakerSe.arc</CODE>.
<li><SPAN class="argument">msgBuf</SPAN>: Passes the address where the message file was loaded. Load <CODE>home.csv</CODE> if a Save Data warning is necessary when resetting or returning to the Wii Menu, and load <CODE>home_nosave.csv</CODE> if no warning is necessary.<font color="red"><B>Note:</B> With WiiWare applications, the <SPAN class="argument">messageFlag</SPAN> setting may cause a warning to be displayed even if the application loaded <CODE>home_nosave.csv</CODE>. If no warning is necessary, you must separately set <SPAN class="argument">messageFlag</SPAN> to an appropriate value.</font>
<li><SPAN class="argument">messageFlag</SPAN>: If <CODE>home.cvs</CODE> was loaded in <SPAN class="argument">msgBuf</SPAN>, use this flag to control the message(s) displayed.
<li><SPAN class="argument">configBuf</SPAN>: Passes the address where the button settings file data displayed on the initial screen was loaded.  For two buttons, use <CODE>config.txt</CODE> under the <CODE>HomeButton2</CODE> folder; for three buttons, use <CODE>config.txt</CODE> under the <CODE>HomeButton3</CODE> folder.
<li><SPAN class="argument">configBufSize</SPAN>: Size of the file that was loaded by <SPAN class="argument">configBuf</SPAN>.
<li><SPAN class="argument">mem</SPAN>: If a memory allocator was prepared by the application, this is <CODE>NULL</CODE>. If you are managing the allocator using the HBM Library, allocate memory of <CODE>HBM_MEM_SIZE</CODE> and pass its starting address in this argument.
<li><SPAN class="argument">memSize</SPAN>: Size of the work region used by the library. If you are not using the allocator, this is <CODE>HBM_MEM_SIZE</CODE>.
<li><SPAN class="argument">pAllocator</SPAN>: If memory allocation is controlled by the application, this sets a pointer to the memory allocator. When you are leaving the creation of the memory allocator up to the HBM library, set this to <CODE>NULL</CODE>.
<li><SPAN class="argument">sound_callback</SPAN>: Callback function when issuing a sound. If not necessary, <CODE>NULL</CODE>.
<li><SPAN class="argument">backFlag</SPAN>: HOME Menu background flag (set to zero for translucent background when HOME Menu is displayed; set to 1 for opaque background when HOME Menu is displayed).
<li><SPAN class="argument">region</SPAN>: Set this to the console's language setting. Region number (specify as <CODE>SC_LANG_XXX</CODE>).
<li><SPAN class="argument">frameDelta</SPAN>: Amount of change per frame (for 60 frames, set to 1.0; for 50 frames, set to 1.2; for 30 frames, set to 2.0).
<li><SPAN class="argument">adjust</SPAN>: When the aspect ratio is 4:3, <CODE>adjust.x = 1.0f</CODE> and <CODE>adjust.y = 1.0f</CODE>. When the aspect ratio is 16:9, <CODE>adjust.x = 832.f/608.f</CODE> and <CODE>adjust.y = 1.0f</CODE>. This has no relationship to resolution or the VI value.
<li><SPAN class="argument">cursor</SPAN>: 0 (Fixed value).
</ul>

<a id="intro_2" name="intro_2"></a>
<h2>Using a Memory Allocator</h2>
<p>The settings of <SPAN class="argument">mem</SPAN>, <SPAN class="argument">memSize</SPAN>, and <SPAN class="argument">pAllocator</SPAN> (members of the <A href="hbm_HBMDataInfo.html"><CODE>HBMDataInfo</CODE> structure</a> passed to the <A href="hbm_HBMCreate.html"><CODE>HBMCreate</CODE></A> function) change depending on where the memory allocator is prepared. When <SPAN class="argument">pAllocator</SPAN> is set, that setting is given priority and used.</p>


<a id="intro_2_1" name="intro_2_1"></a>
<h2>Notes When Using the HBMCreateSound Function </h2>
<p>The following processes are performed by the <CODE>HBMCreateSound</CODE> function. <br />There is a possibility that this function will overwrite the <CODE>AXRegisterCallback</CODE> setting, so call this function only after the user's sound initialization has ended.</p>

<p>When AI and AX initialization are not performed</p>
<pre><code>AIInit( NULL );
AXInit();
</code></pre>

<p>Always</p>
<pre><code>HBMMIXInit();
HBMSYNInit();
HBMSEQInit();

/*Initialize the Sound Data Archive*/
ARCInitHandle(...);
      :

/* Sound thread start*/
OSCreateThread(...);
      :

AXRegisterCallback(...);
</code></pre>

<p><B>Note:</B> The <CODE>AXRegisterCallback</CODE> function saves the user callback, and when HBM processing has finished within the callback, it calls the function set by the user.</p>

<H2>Making the HOME Menu Background Translucent </H2>
<p>It is possible to choose one of two types of backgrounds when the HOME Menu is being displayed: a semi-transparent background through which the application screen is visible, and an opaque background through which the application screen is not visible.<br> The background can be changed by the <SPAN class="argument">backFlag</SPAN> member of the <a href="hbm_HBMDataInfo.html"><CODE>HBMDataInfo</CODE> structure</a>, which is passed to the <a href="hbm_HBMCreate.html"><CODE>HBMCreate</CODE></a> function.
</p>


<a id="intro_3" name="intro_3"></a>
<h2>Console and Wii Remote Settings</h2>
<p>The following settings can be configured using the HOME Menu:</p>
<ul class="index">
<li>Wii Remote Volume Setting
<li>Wii Remote Rumble Setting
</ul>
<p>These items, which must be set on the console or Wii Remote, are saved when you exit the HOME Menu.</p>
<a id="intro_4" name="intro_4"></a>
<h2>Simple Pairing with the Wii Remote</h2>
<p><font color="red">If the application is performing simple pairing with a Wii Remote, it must suspend simple pairing 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>
<a id="intro_5" name="intro_5"></a>
<h2>Notes for a KPADRead Value of Zero</h2>
<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>
<a id="intro_4_1" name="intro_4_1"></a>
<h2>With No Support for Classic Controllers</h2>
<p>
If 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>.
</p>

<a id="intro_2_2" name="intro_2_2"></a>
<H2>Making the HOME Menu Background Translucent </H2>
<p>It is possible to choose one of two types of backgrounds when the HOME Menu is being displayed: a semi-transparent background through which the application screen is visible, and an opaque background through which the application screen is not visible.<br> The background can be changed by the <SPAN class="argument">backFlag</SPAN> member of the <a href="hbm_HBMDataInfo.html"><CODE>HBMDataInfo</CODE> structure</a>, which is passed to the <a href="hbm_HBMCreate.html"><CODE>HBMCreate</CODE></a> function.
</p>

<a id="projection" name="projection"></a>
<h2>Projection Matrix Settings During Rendering</h2>
<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>
</p>
<p>For 4:3 Settings:</p>
<pre><code>f32 viRateX = viWidth  / 670.f;
f32 viRateY = viHeight / 456.f;
MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 304.0f, viRateX * 304.0f, 0.0f, 500.0f);
</code></pre>
<p>For 16:9 Settings:</p>
<pre><code>f32 viRateX = viWidth  / 686.f;
f32 viRateY = viHeight / 456.f;
MTXOrtho(projMtx, viRateY * 228.0f, -viRateY * 228.0f, -viRateX * 416.0.0f, viRateX * 416.0.0f, 0.0f, 500.0f);
</code></pre>
<p> </p>
<a id="intro_6" name="intro_6"></a>
<h2>Processing Sound Effects</h2>
<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>
<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>
<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>
<a id="intro_7" name="intro_7"></a>
<h2>Updating Sounds</h2>
<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>
<a id="intro_8" name="intro_8"></a>
<h2>Standard Close Process</h2>
<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>
<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 &lt;<I>button number</I>&gt; + 1. When the HOME Menu is running, <CODE><A href="hbm_HBMGetSelectBtnNum.html">HBMGetSelectBtnNum</A></CODE> returns –1.</p>
<p>To call the HOME Menu again after exiting, call <CODE><A href="hbm_HBMInit.html">HBMInit</A></CODE>.</p>
<a id="intro_9" name="intro_9"></a>
<h2>Forced Close Process</h2>
<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.
</p>
<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>
<a id="intro_10" name="intro_10"></a>
<h2>Notes for the Stack Size of the Sound Thread</h2>
<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>
<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>
<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>
</p>
<br> <br> <a id="mount" name="mount"></a>
<h4>Typical Implementation for Entering and Leaving HOME Menu </h4>
<ul class="list">
<li><a href="#inout_0">When Entering the HOME Menu</a>
<li><a href="#inout_1">When Leaving the HOME Menu</a>
</ul>
<br style="clear:both;"> <br> <a id="inout_0" name="inout_0"></a>
<h2>When Entering the HOME Menu</h2>
<ul>
<li>Functions that should be called before entering the HOME Menu
</ul>
<pre><code>// Set floating point/integer fast cast feature
OSInitFastCast(void);
</code></pre>
<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>
</p>
<ul>
<li>GX functions that have an effect on the HOME Menu
</ul>
<pre><code>// Whether or not to allow updates to the color buffer
GXSetColorUpdate(GX_TRUE);
</code></pre>
<pre><code>// Clipping functions
GXSetScissor( *1 );
GXSetScissorBoxOffset( *1 );
</code></pre>
<pre><code>// Viewport
GXSetViewport( *1 );
// Other viewport-related functions
</code></pre>
<pre><code>// Projection
GXSetProjection( *1 );
// Other projection-related functions
</code></pre>
<pre><code>// Frame buffer-related functions
GXSetCopyFilter( *2 );
GXSetDispCopyDst( *1 );
GXSetDispCopySrc( *1 );
// Other frame buffer-related functions
</code></pre>
<p>For these functions, set values on the application side before starting the HOME Menu.<br> After the HOME Menu has ended, 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>
<ul>
<li>Wii Remote Processing
</ul>
<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>
<ul>
<li>Sound Processing
</ul>
<p>On the application side, set the volume to 0 (zero) for all sound playback, and shut down all effects for AUX_A through AUX_C.</p>
<p>
<font color="red"><B>Note:</B> <CODE>AXSetMasterVolume</CODE> also lowers the volume for the HOME Menu itself. Do not use this function.</font><br />
</p>
<h5>When an Application Uses NintendoWare </h5>
<pre><code>// Set the sound volume to 0 (zero) for all players and pause
nw4r::snd::SoundPlayer::PauseAllSound( true, fadeFrames );

// Clear the effect
void nw4r::snd::SoundSystem::ClearEffect(bus, fadeTime);
</code></pre>
<h5>When an Application Does Not Use NintendoWare </h5>
<pre><code>AXFXReverbHiShutdown()   // When ReverbHi </code></pre>
<p>Use such functions to shut down all sound for AUX_A through AUX_C.<br /><br />Reference: Use a fade to counteract any noise arising from sudden changes in volume. The Wii Menu uses a 300msec fade.</p>
<a id="inout_1" name="inout_1"></a>
<h2>When Leaving the HOME Menu</h2>
<ul>
<li>GX functions, which are called internally by the HOME button
</ul>
<pre><code>// Alpha compare TEV settings<br>GXSetAlphaCompare( GX_ALWAYS,0, GX_AOP_OR, GX_ALWAYS, 0 );</code></pre>
<pre><code>// Z-compare mode settings<br>GXSetZMode(GX_DISABLE, GX_ALWAYS, GX_DISABLE);</code></pre>
<pre><code>// Settings for the number of indirect lookups to use<br>GXSetNumIndStages(0);</code></pre>
<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>
<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>
<pre><code>// Texture coordinate scale settings<br>GXSetTexCoordScaleManually(GX_TEXCOORD0, GX_FALSE, 0, 0);
GXSetTexCoordScaleManually(GX_TEXCOORD1, GX_FALSE, 0, 0);</code></pre>
<pre><code>// Cylinder wrapping settings<br>GXSetTexCoordCylWrap(GX_TEXCOORD0, GX_FALSE, GX_FALSE);
GXSetTexCoordCylWrap(GX_TEXCOORD1, GX_FALSE, GX_FALSE);</code></pre>
<pre><code>// Culling control<br>GXSetCullMode(GX_CULL_NONE);</code></pre>
<pre><code>// Gamma correction for pixels being copied from EFB to XFB<br>GXSetDispCopyGamma(GX_GM_1_0);</code></pre>
<pre><code>// Fog settings<br>GXSetFog(GX_FOG_NONE, 0, 0, 0, 0, (GXColor){ 0, 0, 0, 255 });</code></pre>
<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>
<ul>
<li>Sound Processing
</ul>
<p>Be sure to restore the sound volume on the application side. </p>
<h5>When an Application Uses NintendoWare</h5>
<pre><code>// Restore all player sound levels
nw4r::snd::SoundPlayer::PauseAllSound( false, fadeFrames );

// Restore effects
nw4r::snd::SoundSystem::AppendEffect( bus, effect );</code></pre>

<h5>When an Application Does Not Use NintendoWare</h5>
<p>The above does not necessarily apply when leaving the HOME Menu by clicking Wii Menu or Reset.</p>
<ul>
<li>Wii Remote Processing
</ul>
<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. If you want to continue using the Wii Remote speaker in the application, set the speaker to <CODE>WPAD_SPEAKER_ON</CODE> after termination. If you are not using the Wii Remote speaker, set the speaker to <CODE>WPAD_SPEAKER_OFF</CODE> after termination.
</p>
<p><B>Note:</B> When using NintendoWare sounds<br />Set the Wii Remote speaker to <CODE>WPAD_SPEAKER_ON</CODE> after termination as follows.</p>
<pre><code>nw4r::snd::SoundSystem::GetRemoteSpeaker( remote_no ).Shutdown();
nw4r::snd::SoundSystem::GetRemoteSpeaker( remote_no ).Setup();</code></pre>
<br> <a id="homeng" name="homeng"></a>
<H4>HOME Menu Prohibited Icon</H4>
<P>When HOME is pressed during a scene that cannot allow the HOME Menu to be shown, a &quot;HOME Menu Prohibited&quot; icon should be displayed. Embed this icon in the application according to the following specifications. You can check the &quot;HOME Menu Prohibited&quot; icon in the sample demo by pressing the + Button when the HOME Menu is not being displayed.</p>

<h2>Icon Data</h2>
<p>
Convert <CODE>Icon-HomeButtonMenu_is_not_available.tga</CODE> in the <CODE>data/icon</CODE> directory to a file format that can be easily used by the application, and use this converted file. When you convert it, do not change the size or pixel pattern of the original image in any way.
</p>

<h2>Displaying the Icon</h2>
<p>
Display anywhere on the screen that is within the safe frame. Alpha-blend in for 0.25 seconds, show fixed for 1 second, and finally alpha-blend out for 0.25 seconds (linearly interpolated).
</P>


<br>
<h2>Revision History</h2>
<dl class="history">
<dt>2009/11/10</dt><dd>Modified the description for <B>Incorporating into WiiWare</B>.</dd>
<dd>Revised description of Wii remote processing of speakers in <B>When Leaving the HOME Menu</B>.</dd>
<dt>2009/06/01</dt><dd>Revised description of sound effects in <B>When Entering the HOME Menu</B>.</dd>
<dd>Added description of GX function in <B>When Leaving the HOME Menu</B>.</dd>
<dt>2009/01/30</dt><dd>Integrated with the page on notes for implementation, and corrected content.</dd>
<dd>Revised <B>Notes for a KPADRead Value of Zero</B>.</dd>
  <dt>2008/09/24
  <dd>Revised <B>Notes for a KPADRead Value of Zero</B>.
  <dd>Added <B>With No Support for Classic Controllers</B>.
  <dd>Revised terminology.
  <dt>2008/02/07
  <dd>Added Wii Remote processing information when leaving the HOME Menu.
  <dt>2008/02/01
  <dd>Added text about the use of WiiWare to <B>Special Libraries</B> and <B>Incorporating into Applications</B>.
  <dt>2007/11/26
  <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>.
<dd>Revised notes related to the sound thread's stack size and resumption of simple pairing.
  <dt>2007/09/28
  <dd>Added cautions related to the stack size of the sound thread and restarting of simple pairing.
  <dt>2007/09/03
  <dd>Added precautions related to the sound fade-out time. Removed the item related to sound customization.
  <dt>2007/05/09
  <dd>Revised the description for the SDK version.
  <dt>2007/04/12
  <dd>Added information to <B>Incorporating into Applications</B>.
  <dd>Added the values that are set to <B>When Leaving the HOME Menu</B>.
  <dt>2007/01/30
  <dd>Revised <B>Typical Implementation for Entering and Leaving the HOME Menu</B>.
  <dd>Revised page layout.
  <dt>2006/12/18
  <dd>Revised <B>Processing Sound Effects</B>.
  <dt>2006/11/11
  <dd>Added information to <B>Incorporating into Applications</B>.
  <dd>Deleted information about manual viewer and added a section about special libraries.
  <dt>2006/10/19
  <dd>Manual edition (added <B>Displaying the Manual from the HOME Menu</B>).
  <dt>2006/10/02
  <dd>Initial version.
</dl>
<HR>
<P>RVL-06-0172-001-V<br>CONFIDENTIAL</P>
</BODY>
</HTML>