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 for displaying and setting information related to the Wii Remote.
For descriptions of the HOME Menu's functionalities and each of its buttons, see the Wii Operations Manual.
Chapter 11 of the Wii Programming Guidelines addresses the HOME Menu. Read this chapter of the Guidelines before implementing the HOME Menu.
Note:
Currently, using the library as an RSO leads to the following kinds of bugs.
Callback process is called after HBMDelete. Using the HOME Menu from an RSO causes memory to be accessed after unlinking.
When deleting the library from memory, after running HBMDelete on the application side, check that the return value of running the WPADProbe function against the connected Wii Remote channel is not WPAD_ERR_BUSY, and then deallocate the RSO or memory.
Applications use the following libraries.
| Application Types | Library Used |
|---|---|
| Disc Applications | homebuttonLib[D].a |
| WiiWare Applications | homebuttonLib.nwm[D].a |
Note: The homebuttonLib.vcmv[D].a file is a library that can be used only with certain channel applications. Do not use this for ordinary applications.
HBMCreate Function
HBMCreateSound Function
Link the homebuttonLib[D].a file and embed the shared resource data contained in the dvddata/HomeButton2 directory into the application's project.
To start the HOME Menu, call HBMCreate then HBMInit in the application source code, in that order; next, call HBMCalc and HBMDraw in the main loop.
The HOME Menu can be incorporated in several ways:
HBMCreate function.
HBMCreateSound function.
HBMInit function to initialize internal library variables.
HBMDraw function to display the HOME Menu.
HBMDeleteSound and HBMDelete functions.
HBMCreate and HBMCreateSound functions during, for example, game initialization.
HBMInit function to initialize internal library variables.
HBMDraw function to display the HOME Menu.
HBMDelete and HBMDeleteSound functions to release the instances.
HBMCreate function during, for example, game initialization.
HBMCreateSound function.
HBMInit function to initialize internal library variables.
HBMDraw function to display the HOME Menu.
HBMDeleteSound function.
HBMDelete function to release the instance.
Note: For details on introducing WiiWare, see the WiiWare Support Guide.
The following items are passed to the HBMCreate function's argument, HBMDataInfo:
Note: HBMDataInfo must be retained until the HBMDelete function is called.
HomeButton2).
| Japan | English | German | French | Spanish | |
|---|---|---|---|---|---|
| Disc | homeBtn.arc | homeBtn_ENG.arc | homeBtn_GER.arc | homeBtn_FRA.arc | homeBtn_SPA.arc |
| WiiWare | LZ77_homeBtn.arc | LZ77_homeBtn_ENG.arc | LZ77_homeBtn_GER.arc | LZ77_homeBtn_FRA.arc | LZ77_homeBtn_SPA.arc |
| Italian | Dutch | Chinese | Korean | ||
| Disc | homeBtn_ITA.arc | homeBtn_NED.arc | homeBtn_CHN.arc | homeBtn_KOR.arc | |
| WiiWare | LZ77_homeBtn_ITA.arc | LZ77_homeBtn_NED.arc | LZ77_homeBtn_CHN.arc | LZ77_homeBtn_KOR.arc |
SpeakerSe.arc and WiiWare applications load Huf8_SpeakerSe.arc.
home.csv if a Save Data warning is necessary when resetting or returning to the Wii Menu, and load home_nosave.csv if no warning is necessary.Note: With WiiWare applications, the messageFlag setting may cause a warning to be displayed even if the application loaded home_nosave.csv. If no warning is necessary, you must separately set messageFlag to an appropriate value.
home.cvs was loaded in msgBuf, use this flag to control the message(s) displayed.
config.txt under the HomeButton2 folder; for three buttons, use config.txt under the HomeButton3 folder.
NULL. If you are managing the allocator using the HBM Library, allocate memory of HBM_MEM_SIZE and pass its starting address in this argument.
HBM_MEM_SIZE.
NULL.
NULL.
SC_LANG_XXX).
adjust.x = 1.0f and adjust.y = 1.0f. When the aspect ratio is 16:9, adjust.x = 832.f/608.f and adjust.y = 1.0f. This has no relationship to resolution or the VI value.
The settings of mem, memSize, and pAllocator (members of the HBMDataInfo structure passed to the HBMCreate function) change depending on where the memory allocator is prepared. When pAllocator is set, that setting is given priority and used.
The following processes are performed by the HBMCreateSound function.
There is a possibility that this function will overwrite the AXRegisterCallback setting, so call this function only after the user's sound initialization has ended.
When AI and AX initialization are not performed
AIInit( NULL );
AXInit();
Always
HBMMIXInit();
HBMSYNInit();
HBMSEQInit();
/*Initialize the Sound Data Archive*/
ARCInitHandle(...);
:
/* Sound thread start*/
OSCreateThread(...);
:
AXRegisterCallback(...);
Note: The AXRegisterCallback function saves the user callback, and when HBM processing has finished within the callback, it calls the function set by the user.
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.
The background can be changed by the backFlag member of the HBMDataInfo structure, which is passed to the HBMCreate function.
The following settings can be configured using the HOME Menu:
These items, which must be set on the console or Wii Remote, are saved when you exit the HOME Menu.
If the application is performing simple pairing with a Wii Remote, it must suspend simple pairing before processing the HOME Menu. To be safe, however, simple pairing is terminated by executing WPADStopSimpleSync in the HBMInit function. If desired, resume pairing processing after exiting the HOME Menu.
When KPADRead returns zero, the value of KPADStatus is undefined. If this value is used unchanged and HBMUpdate is run, improper behavior may result. When the return value of KPADRead is 0, pass the last normal value obtained in KPADStatus.
If you want to disable Classic Controller values even on the HOME Button Menu for software that does not support Classic Controllers, set use_devtype of the HBMControllerData structure to WPAD_DEV_CORE when the device type obtained by WPADProbe is WPAD_DEV_CLASSIC.
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.
The background can be changed by the backFlag member of the HBMDataInfo structure, which is passed to the HBMCreate function.
Before rendering the HOME Menu with HBMDraw, a designated projection matrix must be passed to GX using the GXSetProjection 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.
For 4:3 Settings:
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);
For 16:9 Settings:
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);
When leaving sound effect (SE) processing to the library, initialize sounds by calling the HBMCreateSound function after HBMCreate, and then call HBMUpdateSound at each frame.
To carry out sound effect processing in the application, set a callback function in the sound_callback member of the HBMDataInfo structure without calling the HBMCreateSound() 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 evt, identify the event type according to the HBMSEV_XXX enumerator; then have the application perform suitable processing.
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.
The sound data (SpeakerSe.arc, provided as a shared resource data), which is set to the spkSeBuf member of the HBMDataInfo structure, 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.)
Sound effect updates and Wii Remote updates are performed by HBMUpdateSound. When updates are performed by the program component on its own behalf, it is not necessary to call HBMUpdateSound.
To obtain the number of the button pressed to exit the HOME Menu, use HBMGetSelectBtnNum. Have your application perform the required processing that corresponds to that button number (return to the system menu, reset, and so on).
When HOME is pressed (or Close is clicked) to exit the HOME Menu, HBMGetSelectBtnNum returns <button number> + 1. When the HOME Menu is running, HBMGetSelectBtnNum returns –1.
To call the HOME Menu again after exiting, call HBMInit.
If the RESET or Power Button on the Wii console is pressed while the HOME Menu is open, call the HBMStartBlackOut function to close the HOME Menu.
Note that the status after a forced reset is the same as after closing the HOME Menu by pressing RESET (the HBMGetSelectBtnNum return value is HBM_SELECT_BTN2).
Use the HBMCreateSound function to create a sound thread in the HBM library. The stack size is 16 KB.
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.
If execution halts due to an insufficient stack size, increase the value of HBM_SND_THREAD_STACK_SIZE by defining it before including hbm.h.
// Set floating point/integer fast cast feature
OSInitFastCast(void);
This is used by the HBM library for the drawing process.
If this function is not called, display of the HOME Menu will be distorted.
Call it once at the start of the application.
// Whether or not to allow updates to the color buffer
GXSetColorUpdate(GX_TRUE);
// Clipping functions
GXSetScissor( *1 );
GXSetScissorBoxOffset( *1 );
// Viewport
GXSetViewport( *1 );
// Other viewport-related functions
// Projection
GXSetProjection( *1 );
// Other projection-related functions
// Frame buffer-related functions
GXSetCopyFilter( *2 );
GXSetDispCopyDst( *1 );
GXSetDispCopySrc( *1 );
// Other frame buffer-related functions
For these functions, set values on the application side before starting the HOME Menu.
After the HOME Menu has ended, reconfigure the values on the application side as needed.
*1 For these functions' arguments, substitute items appropriate to the application.
*2 For this function's arguments, substitute application-appropriate items to items other than antialiasing. Turn antialiasing off.
Do not perform simple pairing while in the HOME Menu. Halt it before starting the HOME Menu.
However, to be safe, WPADStopSimpleSync is called within HBMInit to stop processing.
Resume simple pairing in the application after exiting from the HOME Menu, if desired.
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.
Note: AXSetMasterVolume also lowers the volume for the HOME Menu itself. Do not use this function.
// 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);
AXFXReverbHiShutdown() // When ReverbHi Use such functions to shut down all sound for AUX_A through AUX_C.
Reference: Use a fade to counteract any noise arising from sudden changes in volume. The Wii Menu uses a 300msec fade.
// Alpha compare TEV settings
GXSetAlphaCompare( GX_ALWAYS,0, GX_AOP_OR, GX_ALWAYS, 0 );// Z-compare mode settings
GXSetZMode(GX_DISABLE, GX_ALWAYS, GX_DISABLE);// Settings for the number of indirect lookups to use
GXSetNumIndStages(0);// TEV swap table settings
GXSetTevSwapModeTable(GX_TEV_SWAP_0, GX_CH_RED, GX_CH_GREEN, GX_CH_BLUE, GX_CH_ALPHA);// Settings for the swap mode for swapping to a given TEV stage
GXSetTevSwapMode(GX_TEVSTAGE0, GX_TEV_SWAP0, GX_TEV_SWAP0);// Texture coordinate scale settings
GXSetTexCoordScaleManually(GX_TEXCOORD0, GX_FALSE, 0, 0);
GXSetTexCoordScaleManually(GX_TEXCOORD1, GX_FALSE, 0, 0);// Cylinder wrapping settings
GXSetTexCoordCylWrap(GX_TEXCOORD0, GX_FALSE, GX_FALSE);
GXSetTexCoordCylWrap(GX_TEXCOORD1, GX_FALSE, GX_FALSE);// Culling control
GXSetCullMode(GX_CULL_NONE);// Gamma correction for pixels being copied from EFB to XFB
GXSetDispCopyGamma(GX_GM_1_0);// Fog settings
GXSetFog(GX_FOG_NONE, 0, 0, 0, 0, (GXColor){ 0, 0, 0, 255 });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.
Note: Values in parentheses are the actual values set internally by the HOME button.
Be sure to restore the sound volume on the application side.
// Restore all player sound levels
nw4r::snd::SoundPlayer::PauseAllSound( false, fadeFrames );
// Restore effects
nw4r::snd::SoundSystem::AppendEffect( bus, effect );The above does not necessarily apply when leaving the HOME Menu by clicking Wii Menu or Reset.
Simple pairing for the Wii Remote is suspended if it is active when the HOME Menu is executed.
Resume simple pairing in the application, if desired.
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 WPAD_SPEAKER_ON after termination. If you are not using the Wii Remote speaker, set the speaker to WPAD_SPEAKER_OFF after termination.
Note: When using NintendoWare sounds
Set the Wii Remote speaker to WPAD_SPEAKER_ON after termination as follows.
nw4r::snd::SoundSystem::GetRemoteSpeaker( remote_no ).Shutdown();
nw4r::snd::SoundSystem::GetRemoteSpeaker( remote_no ).Setup();When HOME is pressed during a scene that cannot allow the HOME Menu to be shown, a "HOME Menu Prohibited" icon should be displayed. Embed this icon in the application according to the following specifications. You can check the "HOME Menu Prohibited" icon in the sample demo by pressing the + Button when the HOME Menu is not being displayed.
Convert Icon-HomeButtonMenu_is_not_available.tga in the data/icon 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.
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).
RVL-06-0172-001-V
CONFIDENTIAL