MY NES GTK EDITION
------------------
Is a multi-platform edition for My Nes Emulator;
A Nintendo Entertainment System / Family Computer (Nes/Famicom) Emulator written in C#.

Copyright © Alaa Ibrahim Hadid 2009 - 2021
All rights reserved.

Email: alaahadidfreeware@gmail.com

My Nes Official Repository: <https://github.com/alaahadid/My-Nes>
My Nes Official Wiki: <https://github.com/alaahadid/My-Nes/wiki>
My Nes Issues Board (please report bugs here): <https://github.com/alaahadid/My-Nes/issues>
My Nes Contact Email: <mailto:alaahadidfreewares@gmail.com>

Introduction
---------------------------------------------------------------------------------------------------------
My Nes GTK  is a multi-platform edition for My Nes; My Nes SDL  is the emulation interface for My Nes GTK.
My Nes GTK can be used as a launcher for My Nes SDL which it's a command-line based application. Also
you can use My Nes SDL alone if you like to use the command-lines or another powerful launcher end 
like Emulators Organizer < http://sourceforge.net/projects/emusorganizer/ >

My Nes is A Nintendo Entertainment System / Family Computer (Nes/Famicom) emulator written in C#. 
An open source .net freeware, licensed under the GNU GENERAL PUBLIC LICENSE; Version 3, 29 June 2007.

My Nes is meant to be simple, powerful and accurate Nes emulator. The main goal of My Nes is to be as accurate as possible and brings
the best game play experince possible.

My Nes can pass all basic nes tests that test nes hardware behaviors, such as cpu 6502 instructions, 
ppu timing .... etc. However, My Nes pass most of these tests (known at development time of current version) 
without any kind of HACKING (changing some code to make a test pass), by emulating the exact hardware behavior.

My Nes Able to decode nes colors without the need of using palette, includes gray scale and emphasize. For NTSC, PALB and DENDY.
Expect real NES COLORS like it should be in real TV !!
Also the exact audio mixer as descriped at http://wiki.nesdev.com/w/index.php/APU_Mixer (i.e. low-pass and high-pass filters) is implemented.
Video and audio outputs are configured carefully to produce video and sound as accurate as possible, 
also My Nes allows user to configure some of these settings to suit their needs.

If you are looking for an easy-to-use Nes emulator, meant for game play expericne and provides accuracy that very close to the real hardware, 
My Nes is a one that worth a try !


System Requirements
---------------------------------------------------------------------------------------------------------

- Hardware:
CPU: 2400 MHz or higher. Multicore CPU is recommended.
RAM: 512 MB or higher.

- For Windows® Users:
Works with Windows® XP SP3, Vista, Seven, 8, 8.1 and 10; X86 or X64.
Microsoft .NET Framework 4.
GTK# for windows; For more info and downloads please visit http://www.mono-project.com/GtkSharp
(Optional to run My Nes GTK, hence you can use My Nes SDL alone). 

NOTE: If MyNesGTK fails to launch:
Go to folder "C:\Program Files (x86)\GtkSharp\2.12\bin", copy all files then paste them in MyNesGTK folder.

- For Linux users:
. MyNesGTK should work on all platforms that can run mono gtk#.
. Mono runtime and gtk-sharp; For more info and downloads please visit http://www.mono-project.com/GtkSharp (only mono runtime is needed)
  (Problems with GTK# ? maybe this command help: sudo apt-get install gtk-sharp2-examples gtk-sharp3-examples)
. SDL2, SDL2_ttf and SDL2_image. 

For example, installing SDL2 libraries on Ubuntu:
// SDL2
sudo apt-get install libsdl2-2.0-0
sudo apt-get update
// SDL2_image
sudo apt-get install libsdl2-image-2.0-0
sudo apt-get update
// SDL2_ttf
sudo apt-get install libsdl2-ttf-2.0-0
sudo apt-get update

Features And Specification
---------------------------------------------------------------------------------------------------------
- My Nes GTK Interface Features
Uses GTK# which is an easy-to-use multi-platform interface.
A good launcher interface, allows to easily select and run games.
Uses NesCart DB to show and use accurate game information.
Allows to easily edit and change the emulation settings.

- My Nes SDL
Run game in windowed or fullscreen mode with useful video options like keep aspect ratio.
Ability to save snapshots of current game.
Save and load state ability.

- My Nes Core Features

• Accuracy, My Nes pass almost all known nes tests by emulating the real hardware behaviors without any kind of emulation 
  hack.
• Multi-threaded Emulator, the emulation process run in thread separated from renderer threads. 
This may improve 
  performance especially with multi core cpus. 

My Nes Emulation Specification

• CPU 6502: All CPU 6502 instructions implemented including the so called illegal opcodes.
  Exact interrupt timings like interrupt check before the last instruction behavior.
• APU: all Nes 5 sound channels, MMC5 external sound channels and VRC6 external sound channels.
  Emulates the APU-CPU write/read behaviors (exact apu clock timing)
  Exact Mixer as descriped at http://wiki.nesdev.com/w/index.php/APU_Mixer (i.e. low-pass and high-pass filters) 
  Thus, the audio process works like this:
  EMU OUTPUT at ~1.79 MHz => 
  high-pass filter at 90 Hz => 
  high-pass filter at 440 Hz => 
  low-pass filter at 14 kHz => 
  write samples into playback buffer (i.e. play sound).
• PPU: Picture Processor Unit as described in the wiki docs http://wiki.nesdev.com/w/index.php/PPU_rendering 
  is implemented (as close as possible) with exact timing, also ppu vram-bus and io-bus are implemented as well.
• Colors: Ability to decode nes colors without the need of using palette, includes gray scale and emphasize. For NTSC, PALB and DENDY.
  For more info, please see <https://github.com/alaahadid/Nes-Docs/blob/main/Color%20Decoding%20In%20PPU.txt>.
• TV Formats: NTSC, PALB and DENDY. 
• Video Output: Resolution can be upscaled from res 256 x 240 nes basic till 1920 x 1080 Full HD and even higher resolutions. 
  Uses Resolution-Blocks-Upscaler method <https://github.com/alaahadid/Resolution-Blocks-Upscaler>.
• Sound Playback: playback frequency can be 22050 Hz, 44100 Hz or 48000 HZ. 
  Bit rate fixed to 16 bit, channels fixed to Mono. Includes built-in wave recorder.
• Mappers And Boards: Implement about 97% of known and documented mappers
• Controllers: 4 players joypads, each joypad is playable through Keyboard, Joystick or XBox360 Game Controller (XInput). 
  Game Genie is implemented as well.

How To Use
---------------------------------------------------------------------------------------------------------
- My Nes GTK:

-- Main Window:
--------------
When you run My Nes GTK using MyNesGTK.exe file, it shows the main window which it acts like a file browser. 
Simply browse for the nes games folder using the browser then select the desired game in the list. 
In the right section, you'll find all available information about selected game like game info loaded from NesCart DB, 
snapshots taken for that game using My Nes ....etc 
Also using the right section you setup game launch options like state load and game genie.

. Start Up Commands (Command Lines):
Allows to enter custom command lines to send to MyNesSDL when launching a game. See "Command-lines" 
section in the end of this document for list of available command-lines and how to use them.

. The Browser
Allows to browse your computer for nes games folder and select the desired game to run.

. On The Right Panel
>Game Info:
Shows selected game file information like game info loaded from Nes Cart DB (if available) and file info like CRC.
>Game Genie:
Can be used to setup the Game Genie settings for selected game. 
* Check "Enable game genie for this game" to active game genie for selected game (once, you'll need to re-active 
the game genie each time you run a game in order to use game genie for that game)
* Use Add and/or Remove buttons to modify the codes for the selected games. You MUST click Save button after finish adding the 
codes in order to use these codes.
* You can refresh the codes from saved file using Reload button. Also the Save button will save these codes into the same file. 
Each game will have it's own file for Game Genie codes and these code files get saved in the Game Genie Folder.
>State:
Can be used to start selected game with state loaded at specified slot. Simply check "Load state at game start" after you 
select the desired slot from the combobox. My Nes GTK should show a snapshot of the state slot if available for selected game.
>Snapshots:
Shows snapshots taken for selected game that located in the Snapshots folder.

.The Tool Bar Buttons
>Play: Play selected game on the list.
>Stop: Stop current game (if any).
>Refresh info: To refresh selected game info such as states, snaps and sound records. You may want to use this after playing a
 game to check out changes such as states and snaps. 
>Video Settings : Allows to configure emulation video settings.
>Audio Settings : Allows to configure emulation audio settings.
>Input Settings: Allows to configure emulation input settings.
>Folders Settings : Allows to configure emulation folders/files settings.
>Preferences: Allows to configure emulation general settings.
>About My Nes GTK: Shows information about My Nes GTK resources and copyright notices.
>Help: Open the help document.

NOTES:

My Nes GTK will remember the latest game played after closing it.
Changing a game selection will clear Game Genie and State settings.
Snapshots tab get refreshed automatically each time you change the file selection, the snapshot files MUST be located in the Snapshots 
folder that specified in the Paths Settings . 

-- Video Settings:
------------------
Allows to configure emulation video settings directly.

To show the video settings dialog, simply go to Settings>Video from the main menu, click on the Video Settings button on the tools bar 
or press CTRL+ALT+V.

. Enable Resolution Upscale: if set, the emu will upscale nes rendering resolution into res set by "Resolution" option below, otherwise emu will use Nes default res 256 x 240.
Please note that this option does not effect window size.

. Resolution: set the rendering resolution to use when rendering video.
My Nes SDL Renders video from res 256 x 240 nes basic till 1920 x 1080 Full HD, uses Resolution-Blocks-Upscaler method <https://github.com/alaahadid/Resolution-Blocks-Upscaler>. 
Whatever selected res is, it will be stretched to the window/video size. Keep aspect ratio option will try as much as possible to keep the aspect ratio of res selected.
The image quality also depends on filter used for scaling from selected res: linear or point.

. Auto stretch window to fit a specific size given below (windowed mode only): If set, the emulation window will auto resize itself to fit the resizing value giving.

. Stretch Multiply (windowed mode only, when option above is active): If "Auto resize window to fit emulation size" is set, this value will be used to determine the 
window size by multiply this value with. Depending on options above:
If "Enable Resolution Upscale" is set, it will multiply "Resolution" with this value.
If "Enable Resolution Upscale" is not set, it will be multiply of 640 x 480 NTSC / 576 x 520 PALB-DENDY

. Keep aspect ratio: Indicates if the renderer should keep the aspect ratio when stretching the nes output video image. 
Whatever the selected resolution, when rendering into a bigger/smaller screen (window size or fullscreen resolution) the renderer needs to stretch the image. 
This options determine if the aspect ratio of nes resolution should remain or the renderer will stretch the image to fit the screen 
(window size or fullscreen resolution).

. Fullscreen: if set, the emulation will start in fullscreen. You can switch between windowed and fullsceen modes any time using F12 key.

. Fullscreen display: select the display to use when MyNesSDL go into fullscreen mode.

. Fullscreen mode: select the mode to use when MyNesSDL go into fullscreen mode. This changes depending on display selected in option above.
Note:
If the fullscreen display and fullscreen mode comboboxes become inactive (display no entry), please restart My Nes GTK then try again.
This usually happens after playing a game using MyNesSDL then opening the video settings dialog. 

. VSync: indicates if the renderer should use VSync. May reduce shettering in fullscreen.

. Show notifications: Indicates if the renderer should show important messages (Like snapshot taken, state saved ...etc) 

. Show FPS: Indicates if the renderer should show the FPS (Frames Per Seconds) on the top left corner of the render screen.

. Filter (scaling filter): Specify the scaling filter to use when rendering. 

. Adjust Brightness: use brightness adjustment for video. Enabling this option may affect performance but may render clearer video.

. Brighntess Level: if the option above is set, this value will be used as brightness, it can be 0-100%.

Click Defaults button to reset all settings to it's defaults.
Click OK button to save settings. Note that changes take effect the next time you play a game, changing settings during play time will not affect emulation.
Click Cancel button to discard changes.


-- Audio Settings:
-----------------
Allows to configure emulation audio settings.

To show the audio settings dialog, simply go to Settings>Audio from the main menu, click on the Audio Settings button on the tools bar or press CTRL+ALT+A.

. Audio playback enabled: indicates if the sound playback should be enabled or not. Note if this option is disabled the SDL Audio 
component will not initialize at emulation start.

. Enable internal filters: indicates if the internal sound filters are enabled or not. Disabling this option may improve performance but it is recommended
to be enabled.
When enabled, the audio process works like this (as described in wiki):
EMU OUTPUT at ~1.79 MHz => high-pass filter at 90 Hz => high-pass filter at 440 Hz => low-pass filter at 14 kHz => low-pass filter at playback freq (i.e. 44100 Hz for default) => write samples into playback buffer (i.e. play sound). 
When this option is disabled, the filters order will be like this:
EMU OUTPUT at ~1.79 MHz => low-pass filter at playback freq (i.e. 44100 Hz for default) => write samples into playback buffer (i.e. play sound).

. Use My Nes Mixer: if set, My Nes will use the internal mixer which customized to produce the best quality possible. Disable this if you would like to use the standard mixer that described in the wiki (default nes mixer).

. Device/Driver: select the audio device/driver to use for audio.

. Channel XXX enabled (xxx is the name of the channel): indicates if a sound channel output is enabled or not. 

Click OK button to save settings. Note that changes take effect the next time you play a game, changing settings during play time will not affect emulation.
Click Reset To Defaults button to reset all audio settings to defaults.
Click Cancel button to discard changes.


-- Input Settings:
-----------------
Allows to configure emulation audio settings.

To show the input settings dialog, simply go to Settings>Input from the main menu, click on the Input Settings button on the tools bar or press CTRL+ALT+E.

. Change control mapping for: you may want to switch this first, allows to select which control you want to change mapping for.
. Input device to use: allows to select which input device that connected to your machine to use for the controller selected above.
. Use Joystick: indicate if joystick will be used for this nes device.
. Joystick/Controller Index: zero-based index of the Joystick/Controller device that it is connected and want to use for this nes device. 
. Mappings: is the button on the nes or the shortcut to set the map for.Simply click on the entry to edit the value.

IMPORTANT !!
* Always use APPLY button after making a changes for a selected control (in the first option). For example, you changed the "Input device to use", click
  Apply. You changed the "Joystick/Controller index" click Apply, you changed mappings do click Apply as well.... do this every time you make a change.
* Selected "Input to use" device will be used for the controller selected in the first option.
* Emulation Shortcuts are fixed to use Keyboard only.

Click OK button to save settings.
Click Cancel button to discard changes.


-- Folders Settings:
------------------
Allows to configure the emulation important paths.

To show the folders settings dialog, simply go to Settings>Folders from the main menu, click on the Folders Settings button on the tools bar or press CTRL+ALT+P.

Next to any path field, click Change button to change that field value.

The paths are:

. State folder: the folder where the emulation core save game state files (when you save state)
. Snaps folder: the folder where the emulation core save snapshot files when you take snapshot(s).
. Sound records folder: the folder where the emulation core save sound files when you record sound for game(s). 
. Game Genie codes folder: the folder where the emulation core locate the game genie files to load the game genie codes for a game.
. S-Ram folder: the folder where the emulation core save game save-ram files (if available, only some game support it. 
  Save-Ram is the game data that used to save. in real hardware, these data used to be saved using battery)

Click OK button to save settings. Note that changes take effect the next time you play a game, changing settings during play time will not affect emulation.
Click Cancel button to discard changes.


-- Palette Settings:
--------------------
Allows to configure emulation palette or colors settings.
These palettes are used by nes emulation core to output colors. My Nes include 2 palette generators, 
NTSC palette generator and PALB palette generator. The NTSC palette generator is implemented as described at http://wiki.nesdev.com/w/index.php/NTSC_video
There is no information provided about the PALB palette generator (as the date of this document). 
My Nes implements it as same as the NTSC palette generator with simple change: hue is rotated by 15° from NTSC for default.

My Nes implement the "emphasis" and "monochrome" effect, thus, the palette generated is 512 colors instead of known 64 colors palettes. 
The generators in My Nes able to generate the 512 colors palette. Also My Nes can generate the palette files of 64 colors.

To show the palette settings dialog, simply go to Settings>Palette from the main menu, click on the Palette button on the tools bar or press CTRL+ALT+W.

. Palette to use: configure how's the emulation core chooses a palette when running a game. 
* Auto select: the emulation core selects a palette generator depending on rom region settings (loaded from game file header or from NesCartDB), 
like selecting the NTSC palette generator for NTSC tv format and PALB palette generator for PALB or DENDY tv format.
* NTSC Palette Generator: the emulation core will always use the NTSC palette generator.
* PALB Palette Generator: the emulation core will always use the PALB palette generator.
* Palette File: Use a palette file specified in the text box below.
. Palette file: Specify the palette file to use instead of palette generators. Please note that the "Palette to use" option must be set to "Palette file"
  in order this to work. 
. Edit generator valus of: select the palette generator you want to edit settings for here, NTSC palette generator or PALB palette generator.
. Colors: use the sliders to edit the palette generator you select in the "Edit palette for" combobox.
. Load: load the color slider values from file (you can use this to load defaults as well, simply click this button then load DefaultNTSC.mnpp file).
. Save: save the color slider values into a file that can be loaded later.
. Flat all: reset all color slider into flat value.
. Save as .pal: save current colors values into .pal file.

Click OK button to save settings. Note that changes take effect the next time you play a game, changing settings during play time will not effect emulation.
Click Cancel button to discard changes.


-- Preferences:
---------------
Allows to configure the emulation preferences.

To show the paths settings dialog, simply go to Settings>Preferences from the main menu, click on the Preferences button on the tools bar or press CTRL+ALT+Q.

. Snapshot format: the snapshot format that should be used to save the snapshot file when you take a snapshot.
. Replace snapshot instead of creating numbers for snap files: indicates if the emulation core should replace already save snapshot for a game when you take a snapshot. 
  Otherwise, new file created for each snapshot you take for a game.

. Region setting: the emulation region selection:
* AUTO: the emulation core selects region automatically depending on information provided by game file header or database.
* Force NTSC: the emulation core will always select the NTSC region.
* Force PALB: the emulation core will always select the PALB region.
* Force DENDY: the emulation core will always select the DENDY region.

Click OK button to save settings. Note that changes take effect the next time you play a game, changing settings during play time will not affect emulation.
Click Reset To Defaults button to reset all audio settings to defaults.
Click Cancel button to discard changes.


- My Nes SDL:

-- Standby:
-----------
When you run My Nes SDL using MyNesSDL.exe file without using any command-line (or the application couldn't load the game), it will show the standby 
screen which it's a random output for video. 

-- Command-lines:
-----------------
My Nes SDL is a command-line based application, and thus, you need to use command-lines to use it.

The most important command is the first one, the game file path. The game file path MUST be the 
first command to be sent to My Nes in order to play that game. 
If you like to use command-line without launching a game, My Nes will execute these commands then 
go to the Standby mode. 
If you send the game path anywhere else in the command-lines then My Nes will discard this path 
line, execute the other commands then go to the Standby mode.

Example of a working command-line:

<game-file-path> -fullscreen -console -state.slot2 -state.load

This command-line will first set to fullscreen mode, show console, load the game file at 
<game-file-path>, set state slot to # 2 then load the state.

Note that you should keep one space between each command.

-- List of available command-lines:
----------------------------------
-settings: activate settings-only mode. In this mode, My Nes will only load settings, then
executes the commands that set settings then close. No window nor emu will run.
-opengl: set video driver to opengl.
-direct3d: set video driver to direct3d. Use this if you have problems running My nes in 
Windows such as empty widnow.
-opengles2: set video driver to opengles2.
-opengles: set video driver to opengles.
-software: set video driver to software.
-fullscreen: set fullscreen mode.
-windowed: set windowed mode.
-fps: show fps.
-vsync: enable vsync.
-accelerated: enable acceleration.
-soundon: enable sound playback.
-player1.key: force player 1 to use Keyboard.
-player1.joy: force player 1 to use Joytick. (If connected, otherwise Keyboard will be used.)
-player1.xin: force player 1 to use Xinput (If connected, otherwise Keyboard will be used.)
-player2.key: force player 2 to use Keyboard.
-player2.joy: force player 2 to use Joytick. (If connected, otherwise Keyboard will be used.)
-player2.xin: force player 2 to use Xinput (If connected, otherwise Keyboard will be used.)
-region.auto: set region settings to auto select.
-region.ntsc: set region settings to force NTSC.
-region.pal: set region settings to force PALB.
-region.dendy: set region settings to force DENDY.
-palette.auto: set palette settings to auto select.
-palette.ntsc: set palette settings to force NTSC palette generator.
-palette.pal: set palette settings to force PALB palette generator.
-palette.file: set palette settings to use palette file.

These commands are only used after loading a game, thus, the game path command should be 
presented in order these commands to work.
-state.load: load state at slot specified.
-state.slot0: set state slot to # 0
-state.slot1: set state slot to # 1
-state.slot2: set state slot to # 2
-state.slot3: set state slot to # 3
-state.slot4: set state slot to # 4
-state.slot5: set state slot to # 5
-state.slot6: set state slot to # 6
-state.slot7: set state slot to # 7
-state.slot8: set state slot to # 8
-state.slot9: set state slot to # 9
-gamegenie: activates game genie. My Nes SDL will automatically load available codes at game start.

Copyright Notice
---------------------------------------------------------------------------------------------------------
Please read the file "Copyright Notice.txt" or see the about box in MyNesGTK for more details.

Support
--------------------------------------------------------------------------------------------------
My Nes Official Repository: <https://github.com/alaahadid/My-Nes>
My Nes Official Wiki: <https://github.com/alaahadid/My-Nes/wiki>
My Nes Issues Board (please report bugs here): <https://github.com/alaahadid/My-Nes/issues>
My Nes Contact Email: <mailto:alaahadidfreewares@gmail.com>

END OF README.
Last update: Saturday, 6 May, 2021 05:43
--------------------------------------------------------------------------------------------------