WhineCube Readme

{readme}
WhineCube release 8 beta 0 (C) 2003-2007 WhineCube Team
2007-0x-xx

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 currently run at least one commercial game (without sound).

Licences:
WhineCube's source code is licenced under the terms of the GNU General Public License, version 2. See GPL2.txt.

WhineCube's documentation (this file and all text files in this distribution, except the license files themselves) and also the interface code for WhineCube's debug output system is in the public domain. The WhineCube Team waives all copyright that might be asserted over those files.

System requirements:
Pentium-compatible processor.
Windows xp or Linux/Wine. (It might also run on Windows 2000. If you try, please tell me about it.)
DirectX 9.0c, April 2005.
For advanced 3D graphics (used by all commercial games): Pixel Shaders v2.0 (like a Radeon 9500 or a GeForce 5200 or newer).

Graphics card capability recommended for optimal performance in 2D mode: D3DFMT_YUY2 conversion (maybe 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 is unstable. Also, TAP adapter selection is hard-coded, so it won't work on any computer but mine.
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 hopefully be fixed in a future release.
BAM3K may occasionally stop with an "Invalid memory address" error. This cause of error has not been found, because of its rarity.

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

Option	Switch	Description
Common options:
Frame limit	/nofl	Limits the frame rate to 50 or 60 FPS, depending on video mode. The command line switch turns off the frame limiter.
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		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. Doesn't affect textures.
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.
Disable syscall instruction	/nerf_sc	Allows Freeloader and Action Replay to start.
Enable pixel shaders	/nops	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.
Enable display list recompiler	/nodlr	Experimental technique for speeding up complex 3D graphics. The command line switch disables the display list recompiler.
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	Instead of at first message.
Show UART output		Pipe the terminal output used by the official SDK to the EmuDebug window.
Debugging options:
Debug logging	/degub	Creates a log file.
Individual logs for each program	/rename	Creates separate log files for each program 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. Works like /dtexraw.
Log UART/EmuDebug separately	/sef	Creates a separate log file, emudebug.txt, for the output to the EmuDebug window.
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.
	/wii	Enables Wii-specific features. Very incomplete.

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.
to Duddie and Tratax for DSP documentation and GCemu.
to the OpenVPN project for the TAP-Win32 virtual network card and associated 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 install the complete DirectX 9.0c, 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 can 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 to 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
To avoid my anti-spam filter, make sure the subject line of your e-mail contains "WhineCube".

EOF