
PicchioEngine v0.0.8
====================

Copyright(c)2008 Emanuele Bettidi
=================================

Disclaimer
----------
This software is provided 'as is', without any express or implied
warranty. In no event shall the author be held liable for any loss
or damage arising from the use of this software.
YOU USE IT AT YOUR OWN RISK! If you do not agree with these terms
you should delete PicchioEngine now.

Description
-----------
PicchioEngine is an PC Engine/TurboGrafx 16 emulator whose main purpose
is to document and to preserve.
This software uses the Simple DirectMedia Layer library("SDL", http://www.libsdl.org),
which is included under the terms of the GNU Lesser General Public License
("LGPL", http://www.gnu.org/copyleft/lesser.html).

History
-------
2008/12/02 v0.0.1
 - First public release.
2008/12/07 v0.0.1a
 - Corrected some errors and compiler warnings.
2009/01/23 v0.0.2
 - The system now run at exactly 21477272+(8/11)Hz.
 - Implemented the linear phase low-pass filter using the BLEP synthesis.
   This filter is used to reduce the sampling rate from 3579545+(5/11)Hz to 48kHz.
 - Emulated accurately the RC audio filters present on the DUO-R.
 - Added a preliminary and incomplete PSG emulation.
2009/02/01 v0.0.3
 - The colors of the composite output are accurately reproduced(patent US 5389949).
 - Added fullscreen mode.
 - Now the emulator accept some optional arguments from the CLI.
 - Automatic selection of the PC Engine/TurboGrafx 16 emulation based on the file name.
 - Added support for the rom image files with header.
2009/02/17 v0.0.4
 - Added a temporary and not accurate(only line-based) VDC emulation.
   Note: Only added to test other parts, in future a complete rewriting is necessary.
 - Added support for the rom image files of 384kB.
 - Preliminary and limited support for joysticks.
 - Now some games are playable.
2009/03/02 v0.0.5
 - Added a option to show/hide the video overscan.
 - Added support for the cards Populous and Street Fighter II' CE.
 - Resolved the problem of the missing sprites in some games.
2009/06/23 v0.0.6
 - The configuration is now handled through a file(PicchioEngine.cfg).
 - Removed the possibility to insert optional arguments from the CLI.
   Note: Not a definitive choice.
 - More verbose output.
 - Complete support for joysticks.
 - The input assignments are now redefinable.
2009/08/04 v0.0.7
 - The range of the audio buffer size is now 1~3072 samples.
 - Corrected a bug in the PSG code that affect the starting phase of the waveform generators.
 - Separated the emulation of the two low-pass RC filters(DUO-R) from the BLEP audio synthesis.
 - The high-pass RC filter(DUO-R) now use floating point numbers instead of integers.
 - Optimized version of the BLEP synthesis for processors that support the SSE2 instruction set.
2009/10/09 v0.0.8
 - The binary for Windows is now included.
 - Accurate and complete MultiTap/TurboTap emulation.
 - PC Engine Pad(PI-PD001), TurboPad and AvenuePad6 accurately emulated.
 - Corrected the position of the visible area in hi-res mode.
 - Optimized version of the copy line buffer -> video buffer for processors with SSE2.

Emulation Status
----------------
- CPU near to completion.
  Missing things:
  - RDY line mechanism not implemented.
  - NMI not implemented(not physically used on the PC Engine).
  - The precise timings of the lines IRQ1 and IRQ2 are unknown.
  - The behavior during the first two cycles of the START/RESTART
    sequence is unknown.
  - The precise timing of the change of speed at the RESTART is unknown.
  - The precise timing of the initialization of registers/bits at the
    RESTART is unknown.
  - If the SEL line(IO Port) is set at the RESET is unknown.
  - RESTART not supported.
  Excluding the preceding things, the emulated CPU is INDISTINGUISHABLE
  from a real CPU.
  This is the result of two years of work and hundreds of tests.
- PSG preliminary and incomplete.
- VDC temporary with line-based accuracy.
- VCE preliminary.

To-Do List
----------
- Better FIR filter coefficents(BLEP audio synthesis).
- Better OpenGL support.
- Video scanlines simulation.
- AvenuePad3 and ArcadePad6 emulation.
- Mouse emulation.
- Cycle accurate VDC and VCE emulation.
- More accurate and complete PSG emulation.
- SuperGrafx emulation.

System Requirements
-------------------
- A graphic card with support for OpenGL and rectangular textures
  (GL_TEXTURE_RECTANGLE_ARB) of 2048x2048 pixels.
- A sound card with 2 stereo channels at 16bit and 48000Hz.
- The SDL runtime library(included).

Usage
-----
PicchioEngine <rom image file>
Execute PicchioEngine from CLI with a rom image file as argument.

Configuration File
------------------

 Base settings:

                    value    default   value
  name              type     value     range      description
  ----------------  -------  --------  ---------  ---------------------------------------------------
  console           string   auto      see desc.  select the console to emulate
                                                   auto - automatic selection based on rom image file
                                                   pce  - PC Engine
                                                   tg16 - TurboGrafx 16
  ----------------  -------  --------  ---------  ---------------------------------------------------
  timer_phase       integer  0         0~2        phase between CPU and Timer
  ----------------  -------  --------  ---------  ---------------------------------------------------
  rgb_output        boolean  no                   RGB video output
  ----------------  -------  --------  ---------  ---------------------------------------------------
  controller_port   string   multitap  see desc.  device connected to the console's controller port
                                                   none       - no device connected
                                                   pcepad     - PC Engine Pad
                                                   turbopad   - TurboPad
                                                   avenuepad6 - AvenuePad6
                                                   multitap   - MultiTap/TurboTap
  ----------------  -------  --------  ---------  ---------------------------------------------------
  multitap.port_1   string   turbopad  see desc.  controller connected to the MultiTap/TurboTap port
  ----------------  -------  --------  ---------   none       - no controller connected
  multitap.port_2   string   turbopad  see desc.   pcepad     - PC Engine Pad
  ----------------  -------  --------  ---------   turbopad   - TurboPad
  multitap.port_3   string   turbopad  see desc.   avenuepad6 - AvenuePad6
  ----------------  -------  --------  ---------
  multitap.port_4   string   turbopad  see desc.         
  ----------------  -------  --------  ---------
  multitap.port_5   string   turbopad  see desc.         
  ----------------  -------  --------  ---------  ---------------------------------------------------
  audio_buffer      integer  2048      1~3072     audio buffer size in samples
  ----------------  -------  --------  ---------  ---------------------------------------------------
  scale             integer  2         1~6        scaling factor in window mode
  ----------------  -------  --------  ---------  ---------------------------------------------------
  overscan          boolean  no                   video overscan
  ----------------  -------  --------  ---------  ---------------------------------------------------
  fullscreen        boolean  no                   fullscreen mode
  ----------------  -------  --------  ---------  ---------------------------------------------------
  stretch           boolean  no                   stretch to fill the screen in fullscreen mode
                                                  (preserves the aspect ratio)
  ----------------  -------  --------  ---------  ---------------------------------------------------
  bilinear          boolean  no                   bilinear video interpolation
  ----------------  -------  --------  ---------  ---------------------------------------------------
  pause_key         key      p                    key to pause the emulator
  ----------------  -------  --------  ---------  ---------------------------------------------------
  exit_key          key      escape               key to exit the emulator
  ----------------  -------  --------  ---------  ---------------------------------------------------
  input_joystick    integer  0         0~255      index of the input joystick
  ----------------  -------  --------  ---------  ---------------------------------------------------
  analog_threshold  integer  75        1~100      axis threshold for analog joysticks in percent
  ----------------  -------  --------  ---------  ---------------------------------------------------

 Input settings:

  Format:
   controller <port> <pad> [joystick <index>]
   controller <port> <pad>.<button> [key <key>] [axis <index> <direction>]|[hat <index> <position>]|[button <index>]
   controller <port> <pad>.<button> [axis <index> <direction>]|[hat <index> <position>]|[button <index>] [key <key>]

  <port>      must be an integer between 1 and 5
  <pad>       must be one of these words: pcepad, turbopad, avenuepad6
  <button>    if <pad> is pcepad, must be one of these words:
               i, ii, select, run, up, right, down, left
              if <pad> is turbopad, must be one of these words:
               i, ii, select, run, up, right, down, left, i_turbo_slow, i_turbo_fast, ii_turbo_slow, ii_turbo_fast
              if <pad> is avenuepad6, must be one of these words:
               i, ii, select, run, up, right, down, left, iii, iv, v, vi, i_turbo, ii_turbo, mode, slow
  <key>       must be a value of the type key
  <index>     must be an integer between 0 and 255
  <direction> must be one of these words: +, -, p, n, pos, neg
  <position>  must be one of these words: u, r, d, l, up, right, down, left

 Types:

  accepted boolean values
  -----------------------
  no/yes  n/y  false/true  f/t

  accepted integer values
  -----------------------
  Any integer expressed in decimal form and within the range of the specific setting.

  accepted key values
  -------------------
  Any printable character or one of the followings words:
   backspace  tab  clear  return  pause  escape  space  delete
   kp_0  kp_1  kp_2  kp_3  kp_4  kp_5  kp_6  kp_7  kp_8  kp_9
   kp_.  kp_/  kp_*  kp_-  kp_+  kp_enter  kp_=
   up  down  right  left  insert  home  end  pageup  pagedown
   f1  f2  f3  f4  f5  f6  f7  f8  f9  f10  f11  f12  f13  f14  f15
   numlock  capslock  scrollock
   rshift  lshift  rctrl  lctrl  ralt  lalt
   rmeta  lmeta  lsuper  rsuper  mode  compose
   help  print  sysreq  break  menu  power  euro  undo

Default Input Assignments
-------------------------
See the configuration file.

PicchioEngine Homepage
----------------------
http://www.webalice.it/cicciopetito/

Contact/Help
--------------
e-mail: ciccio_petito@libero.it
