WhineCube Readme

{readme}
WhineCube release 6 (C) 2003-2005
2005-05-08

WhineCube is a GameCube emulator. It loads and executes DOL-, ELF- or GCM-format executables with graphics, pad, DVD and sound emulation, and can also provide massive debug dumps. It has two different cores, an interpreter and a dynamic recompiler. It does not yet run any commercial games.

System requirements:
Pentium-compatible processor Windows xp or later (It might run on Windows 2000. If you try, please tell me about it.)
DirectX 9.0c

Recommended for optimal performance:
A graphics card that supports D3DFMT_YUY2 conversion and hardware T&L (like a GeForce 256 or newer).

Known issues:

PSOLoad2-style DOL reloading is not supported. Attempting it will result in an undefined opcode encounter.
BBA emulation has been nerfed until further notice. (The emulation is active, but no packets are actually sent or recieved.)
Your desktop color depth must be 32 bits, or WhineCube might refuse to start.
Memcards must formatted in WhineCube in order to work properly. Thus you can't import saves from a real Cube.

Usage: whinecube [filename.<dol | elf | gcm>] [switches]

Option	Switch	Description
Common options:
Frame limit		Limits the frame rate to 25 or 30 FPS, depending on video mode.
High refresh rate		Vsync detection is tricky business. In 2D mode, when WhineCube is unable to dectect new frames, the screen is updated at a fixed rate, which defaults to one FPS. This option increases that rate to 25 or 30 FPS, depending on video mode.
Mute audio	/quiet
Wireframe		Only effective in 3D mode. Disables textures, culling, blending, z-compare and alpha-compare.
Flat shading		Only effective in 3D mode.
Force white		Only effective in 3D mode.
Always on top	/aot
Advanced emulation options:
Interpreter	/interp
Recompiler	/rec
	/recd	Dumps PPC disassembly of recompiled areas. Implies /rec.
Cache hack	/cache	A very simple memory cache implementation. This takes care of a few early demos which would not work when loaded with something other than PSUL 1.0. It may cause or fix problems in other demos, too.
Advanced mode	/amode	Activates advanced memory translation mechanisms (BATs and page tables). For use with very advanced stuff (gc-linux).
DMA Audio minimum buffer size		A bigger buffer means more stability but also more lag. Don't mess with this unless you know what you're doing.
Mount GCM on load	/gcm <file>	Loads the specified GCM file into the emulated DVD drive at startup. This works with the DVD emulation and is ignored if you've loaded a GCM for execution.
Timing mode:		Timing affects DEC and TB registers, as well as the VI and AI.
Realtime	/rt	This mode acts like as much like a real Cube as possible. It may be unreliable if WhineCube runs slower than a real Cube.
Exact, realistic	/er	The instruction count is used as base, providing the exact same results every time the program is run. This mode should emulate the relative speed between the Gekko's speed and the Cube's other timers more accurately than the other modes, but it can be very slow.
Exact, fast	/ef	The simplest and potentially the fastest mode, but also the most inaccurate. It has some problems, especially with commercial games.
UI options:
Auto-pause		Pauses and unpauses the emulation as the window loses and gains focus.
Software YUYV conversion	/soft2d	For older graphics cards that don't support hardware conversion.
Open EmuDebug output window on load	/edo
Show UART output	/edo_osr	Terminal output used by the official SDK.
Debugging options:
Full instruction dump	/degub	Dumps debug info for every instruction executed. Slow and spacy.
Skip instructions	/skip%i	Skips the first %i instructions. Ex: /skip123000
Beep	/beep	Emits a low-pitch beep through the PC speaker when a vsync access is detected, a high beep when pad access is detected and a medium beep when recompilation starts/stops.
Lowmem logging	/lowmem	Logs accesses to the low memory area (0 - 0x3100). Implies /interp.
Log graphics	/glog	Logs GX and VI activities.
Log DSP/audio	/alog
Log interrupts	/lint	Also logs accesses to the MSR, DEC, TB and PI registers, and page faults in advanced mode.
Log EXI	/elog
Log BBA	/blog
Log Memcards	/mclog
Log SI(joypads)	/slog
BoUeHR	/bouehr	Break On UnEmulated Hardware or SPR access.
Dump memory	/dumpmem	Dumps main, cache and hardware memory on exit. Does not dump ARAM.
Dump audio	/daudio	Dumps sounds played using the DMA system. Raw 16-bit stereo PCM, big endian.
Dump raw textures	/dtexraw	Dumps encountered GX textures. The dumps are placed in a new subdirectory which is named after the emulated program. File names have this format: <address>_<iteration>_<gcformat><format>.raw. <address> is the physical address of the texture in GameCube memory. <iteration> is the number of times the texture at this address has been changed since the start of the emulation. It's reset on load, so be sure to move the files if you want to save them. <gcformat> is the source format, a hexidecimal digit. <format> is the target format. Can be rgb, i(intensity), a(alpha), c(color index) or t(source format).
Dump PNG textures	/dtex	Dumps textures to PNG format. Is independent of /dtexraw.
Command-line switches:
	/disasm	Makes WhineCube act like a disassembler. Rather messy, but it gets the job done.
	/clog	Logs EXI, memcard, BBA, GP and audio activity. All the hardware, that is.
	/gfdump	Takes a screenshot of every frame, if program goes into 3D mode.

Additional notes:
WhineCube saves its settings in an ini file which is created in the directory where it's run. Most users should not need to change the ini file directly, but it has been designed to be intuitive in case the need should arise. Documentation for the ini file may be added if there is demand for it.

To homebrew coders: I have enclosed source code for a debug output system. Contact me if you have any questions.

Thanks:
to Crazy Nation for lots of useful info in their Source Pack.
to Peter of www.console-dev.de and to Yursoft for YUYV and Pad info in their OpenGC library.
to CrowTRobo for his Audio Demo.
to Epsilon and RealityMan (UltraHLE) for the analog modifier key idea.
to or9 for Dolwin.
to Costis for GCLIB.
to tmbinc for his IPL and 3D code.
to groepaz for YAGCD.
to monk for gcube.
to ector, schibo and F|RES for Dolphin.
to DesktopMan for YUYV info and the EmuDebug idea.
to WinterMute and shagkur for devkitPPC and libogc.
to Aaron Robinson of CXBX for the OOVPA idea.
to Zoltan Csizmadia <zoltan_csizmadia@yahoo.com> for ExtendedTrace, the stack tracing code.

Many thanks to the beta testers, whose feedback helped a lot:
Psyside, Haiku, lrdcheese, ZaBA, s|rens, Knuckles, kurni, Shagkur, Vile324, JinXD, Chrono, Sonic, Ch40sC0d3 and Orphys.

Special Thanks:
to Nullsoft for WinAMP, which sustains me through long hours of coding.
to sleeps for the WhineCube logotype and icon.

FAQ:
Q: Where does the name come from?
A: It evolved from WinCube through WineCube. It doesn't have anything to do with whining, sleeps and I just thought it sounded cool. :)

Q: Can I run commercial games (GCMs) on WhineCube?
A: You can try, but they won't work very well. I'm working on it.

Q: What did you use to write WhineCube?
A: Microsoft Visual C++, the DirectX9 SDK and the pngdib library.

Q: What should I do when WhineCube crashes or freezes? (the emulator itself, not the GameCube program I'm trying to run)
A: Make sure your computer meets the requirements. Update all your drivers. Then make sure your computer is stable (especially with regards to overclocking, memory and power supply). If, after all this, it still doesn't work, contact me.

Q: I got a cryptic error message. How do I figure out what it means?
A: Most of the error messages that may seem cryptic signify some aspect of the Gamecube that haven't been emulated yet. If the program you're trying to run isn't on the Compability List, contact me.

Q: Why does the status bar say NTSC when I'm running a PAL60 program?
A: NTSC and PAL60 are indistinguishable from the emulator's point of view. It shouldn't affect the operation of your program.

Web site: http://whinecube.emulation64.com/

Contact the author:
IRC: #whinecube on Efnet
e-mail: masken@emulation64.com

EOF