WhineCube Readme

{readme}
WhineCube release 7 (C) 2003-2005
2005-07-26

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 logs. It can run at least one commercial game.

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, April 2005 or later.

Graphics card capabilities recommended for optimal performance:
in 2D mode: D3DFMT_YUY2 conversion (like a GeForce 256 or newer.)
in 3D mode: Pixel Shaders v2.0 (I use a Radeon 9800.)

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. It also seems that they are locked to the game that formatted them; all others will say that the card is corrupted. This is due to incomplete DSP emulation and will be fixed in the future.
Very occasionally, BAM3K may stop with an "Invalid memory address" error. This error has not been fixed due to its rare and random nature.

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

Option	Switch	Description
Common options:
Frame limit		Limits the frame rate to 50 or 60 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 50 or 60 FPS, depending on video mode.
Mute audio	/quiet
Wireframe		Disables textures, culling, blending, z-compare and alpha-compare. Only effective in 3D mode.
Force white		Disables lighting and vertex color. 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. Mutually exclusive with Advanced mode.
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 is ignored if you've loaded a GCM for execution.
Enable pixel shaders	/nops	Enables pixel shaders. This is on by default and should stay that way, unless your card doesn't support it, in which case it will be turned off when WhineCube starts. The command line switch disables pixel shaders.
Disable syscall instruction	/nerf_sc	Allows Freeloader and Action Replay to start.
Timing modes:		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 when 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 fastest mode, but also the most inaccurate.
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:
Debug logging	/degub	Creates a log file.
Individual logs for each game	/rename	Creates separate log files for each game that is run, naming the logs using gamename and code if it's a GCM, filename otherwise.
Full instruction dump	/fid	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 audio	/alog	Logs DMA audio activities.
Log DSP	/dsplog	Logs DSP accesses and disassembles loaded DSP code. Also logs ARAM accesses.
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, GX, SI 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.
to Bob Jenkins for his LOOKUP2 hashing 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: When I try to start WhineCube, it complains about a missing DLL file called "d3dx9_25.dll".
A: Download the file from emulation64.com or m3fe.com. You could also update all of DirectX with the very latest version, which can be downloaded from Microsoft. It's over 30 MB, though, vs. the single file which is only 1 MB.

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, libpng and pngdib.

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: I got an error message saying "Invalid memory address". What do I do?
A: Try running the program in Advanced Mode. If the error persists, it is likely due to an access to either the Locked Cache or the EFB, none of which are emulated yet. If you want to send a report to me, make sure you use the Interpreter, as the Recompiler doesn't report invalid memory addresses correctly.

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.

Q: What's with the misspelling "degub.txt"?
A: When I first created the degub system, long before the beginning of WhineCube, I mistyped the word and didn't bother to correct it. I've thought about changing it, but the unusual spelling helps avoid namespace collisions.

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

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

EOF