Merge pull request #297 from ogamespec/main

DumpVideoSignalRus.md

UserManual/PPUPlayer/DumpVideoSignalEng.md

@@ -0,0 +1,98 @@
+# PPUPlayer Video Dump Guide
+
+Requirements:
+- PPUPlayer 2.2+ (https://github.com/emu-russia/breaknes/releases/)
+- Nintendulator (https://www.qmtpro.com/~nes/nintendulator/)
+
+## First run of PPUPlayer
+
+Start PPUPlayer:
+
+![dump_video_001](/UserManual/imgstore/dump_video_001.png)
+
+Select in the settings the PPU revision for which you want to get the video signal dump:
+
+![dump_video_002](/UserManual/imgstore/dump_video_002.png)
+
+Run PPUPlayer in "free flight" (Run PPU). Go to the Current Scan tab and make sure the PPU is alive:
+
+![dump_video_003](/UserManual/imgstore/dump_video_003.png)
+
+## Dump of PPU state in Nintendulator
+
+Run some game in Nintendulator, preferably without a complicated mapper.
+
+Open the debugger and save all of the PPU memory:
+
+![dump_video_004](/UserManual/imgstore/dump_video_004.png)
+
+You will get a file with the extension .ppumem, which can be found somewhere in the depths of your Users/AppData folder.
+
+## Loading PPU state into the PPUPlayer
+
+Select `Load Nintendulator PPU Dump` in the menu `PPU Dumps` and load the PPU memory dump from the Nintendulator.
+
+This will result in something like this:
+
+![dump_video_005](/UserManual/imgstore/dump_video_005.png)
+
+But oops. Something's wrong.
+
+The point is that the Nintendulator only saves the PPU memory, but not the current values of registers $2000 and $2001.
+
+Especially important is register $2000, which sets the Pattern table addresses and sprite size.
+
+To fix this, go to the Debug tab and change the value of register $2000 (for Contra you need to set it to 0x30):
+
+![dump_video_006](/UserManual/imgstore/dump_video_006.png)
+
+It turned out like this:
+
+![dump_video_007](/UserManual/imgstore/dump_video_007.png)
+
+## Turn on the video signal dump
+
+There is only one small thing left to do.
+
+In the menu `PPU Dumps` you need to select `Start video signal dump`, specify the file and then the dump to the video output file of the PPU chip will start automatically.
+
+- For "composite" PPU (2C02/2C07) we dump a float array, each value represents a voltage (signal level)
+- For RGB PPU 4 bytes are dumped (in order R, G, B, SYNC) which correspond to RGB PPU outputs
+
+## RAW Dump
+
+It is possible to get the pixel value before the DAC circuitry instead of the PPU video signal:
+
+![dump_video_008](/UserManual/imgstore/dump_video_008.png)
+
+In this case uint16_t values of the following format will be dumped:
+
+```c++
+		/// <summary>
+		/// Raw PPU color, which is obtained from the PPU circuits BEFORE the video signal generator.
+		/// The user can switch the PPUSim video output to use "raw" color, instead of the original (Composite/RGB).
+		/// </summary>
+		union RAWOut
+		{
+			struct
+			{
+				unsigned CC0 : 1;	// Chroma (CB[0-3])
+				unsigned CC1 : 1;
+				unsigned CC2 : 1;
+				unsigned CC3 : 1;
+				unsigned LL0 : 1;	// Luma (CB[4-5])
+				unsigned LL1 : 1;
+				unsigned TR : 1;	// "Tint Red", $2001[5]
+				unsigned TG : 1;	// "Tint Green", $2001[6]
+				unsigned TB : 1;	// "Tint Blue", $2001[7]
+				unsigned Sync : 1;	// 1: Sync level
+			};
+			uint16_t raw;
+		} RAW;
+```
+
+## Summary
+
+PPUPlayer has become a powerful tool in exploring PPU. There is a real live PPU living inside of it.
+
+Feel free to push the different buttons in PPUPlayer and experiment. If anything, there is also a presentation (nearby).

UserManual/PPUPlayer/DumpVideoSignalRus.md

@@ -0,0 +1,98 @@
+# Руководство по дампу видеосигнала в PPUPlayer
+
+Требования:
+- PPUPlayer 2.2+ (https://github.com/emu-russia/breaknes/releases/)
+- Nintendulator (https://www.qmtpro.com/~nes/nintendulator/)
+
+## Первый запуск PPUPlayer
+
+Запустить PPUPlayer:
+
+![dump_video_001](/UserManual/imgstore/dump_video_001.png)
+
+Выбрать в настройках ревизию PPU, для которого нужно получить дамп видеосигнала:
+
+![dump_video_002](/UserManual/imgstore/dump_video_002.png)
+
+Запустить PPUPlayer в "свободный полёт" (Run PPU). Перейти на вкладку Current Scan и убедиться что PPU живой:
+
+![dump_video_003](/UserManual/imgstore/dump_video_003.png)
+
+## Дамп состояния PPU в Nintendulator
+
+Запустить какую-то игру в Nintendulator, желательно без сложного маппера.
+
+Открыть отладачик и сдампить всю память PPU:
+
+![dump_video_004](/UserManual/imgstore/dump_video_004.png)
+
+Получится файл с расширением .ppumem, который можно найти где-то в недрах вашей папки Users/AppData.
+
+## Загружаем состояние PPU в PPUPlayer
+
+В меню `PPU Dumps` выбрать пункт `Load Nintendulator PPU Dump` и загрузить полученный в Nintendulator дамп памяти PPU.
+
+Получится примерно такое:
+
+![dump_video_005](/UserManual/imgstore/dump_video_005.png)
+
+Но упс. Что-то не так.
+
+Дело в том, что Nintendulator сохраняет только память PPU, но не сохраняет текущие значения регистров $2000 и $2001.
+
+Особенно важен регистр $2000, в котором задаются адреса Pattern table и размер спрайтов.
+
+Чтобы это исправить, переходим на вкладку Debug и меняем значение регистра $2000 (для Contra нужно установить значение 0x30):
+
+![dump_video_006](/UserManual/imgstore/dump_video_006.png)
+
+Получилось такое:
+
+![dump_video_007](/UserManual/imgstore/dump_video_007.png)
+
+## Включить дамп видеосигнала
+
+Осталось за малым.
+
+В меню `PPU Dumps` нужно выбрать пункт `Start video signal dump`, указать файл и после этого автоматически начнётся дамп в файл видеовыхода микросхемы PPU.
+
+- Для "композитных" PPU (2C02/2C07) производится дамп массива float, каждое значение представляет собой напряжение (уровень сигнала)
+- Для RGB PPU дампится 4 байта (в очередности R, G, B, SYNC), которые соответствуют выходам RGB PPU
+
+## RAW Dump
+
+Есть возможность вместо видеосигнала PPU получать значение пикселей до схемы ЦАП:
+
+![dump_video_008](/UserManual/imgstore/dump_video_008.png)
+
+В этом случае будут дампиться значения uint16_t следующего формата:
+
+```c++
+		/// <summary>
+		/// Raw PPU color, which is obtained from the PPU circuits BEFORE the video signal generator.
+		/// The user can switch the PPUSim video output to use "raw" color, instead of the original (Composite/RGB).
+		/// </summary>
+		union RAWOut
+		{
+			struct
+			{
+				unsigned CC0 : 1;	// Chroma (CB[0-3])
+				unsigned CC1 : 1;
+				unsigned CC2 : 1;
+				unsigned CC3 : 1;
+				unsigned LL0 : 1;	// Luma (CB[4-5])
+				unsigned LL1 : 1;
+				unsigned TR : 1;	// "Tint Red", $2001[5]
+				unsigned TG : 1;	// "Tint Green", $2001[6]
+				unsigned TB : 1;	// "Tint Blue", $2001[7]
+				unsigned Sync : 1;	// 1: Sync level
+			};
+			uint16_t raw;
+		} RAW;
+```
+
+## Заключение
+
+PPUPlayer стал мощным инструментов в изучении PPU. Внутри него живёт настоящий живой PPU.
+
+Не стесняйтесь тыкать разные кнопочки в PPUPlayer, экспериментируйте. Если что, имеется также презентация (тут рядом).