OpenPTC 1.0 DOS Distribution Options
--------------------------------------


Console options give users of a PTC distribution control
over aspects of specific internal details that cannot be
expressed in the platform independent OpenPTC API. For
example, one platform may introduce an option string of
"windowed output" which would force the console to output
in a window instead of fullscreen.

You can pass option strings to both consoles and surfaces.
Most options apply to consoles only, some apply to both
surfaces and consoles.

A few options apply to all implementations of OpenPTC,
but most apply to only a specific distribution.

To pass an option to a surface or a console you do the
following:

    // set surface option
    surface.option("enable dithering");

    // set console option
    console.option("windowed output");

Remember that option strings are case independent, and that
its safe to pass an option string that is not supported by
the implementation (the option function just returns false).

For your convenience every implementation of OpenPTC reads
console options from the file "ptc.cfg" in the current dir,
if it exists, when a console is created. This lets you, and
your users pass options strings easily without having to
recompile.

#0. Console Output Options
--------------------------

"Fakemode"
- enables Fakemode output

"Text"
- enables Text output


#1. Options that apply to both surfaces and consoles:
-----------------------------------------------------

"enable dithering"
- enables dithering when copying from this surface or
  console to another surface.
- this option is only a hint. dithering will be enabled
  if it is implemented for this conversion, and dithering
  makes sense here (ie. 32bit->16bit dithering makes sense
  but dithering from 16bit->32bit does not.)
- this option is supported on all implementations of PTC
  thanks to the HERMES library (http://hermes.terminal.at).

"disable dithering"
- disables dithering when copying from this surface or
  console to another surface.
- dithering is disabled for surfaces and consoles by default
- this options is supported on all implementations of PTC.


#2. Options that apply to consoles only
---------------------------------------

"default width [n]"
- this option sets the default width to be used in calls to
  Console::open when a width is not specified in the parameters.
- the parameter 'n' is optional, if it is omitted, the width is
  set back to the original default width. "default width"
- to set your own default width pass an option like this:
  "default width 640".
- this option affects subsequent calls to Console::open.

"default height [n]"
- this option sets the default height to be used in calls to
  Console::open when a height is not specified in the parameters.
- the parameter 'n' is optional, if it is omitted, the height is
  set back to the original default height.  "default height"
- to set your own default height pass an option like this:
  "default height 480".
- this option affects subsequent calls to Console::open.

"default bits [n]"
- this option coarse control over the default pixel format that is
  used when a format is not specified in the parameters to console
  open.
- Valid values for 'n' are 8,16,24 and 32. When '8' is passed,
  the format is set to an 8bit indexed format (256 color palette).
  When 16bit is set, the format is RGB565. When 24bit is set RGB888,
  and when 32bit is set, the format is 32bit RGB888 (with 8 bits
  spare at the top of the integer.)
- the parameter 'n' is optional, if it is omitted, the format is
  set back to the original default format. ie. "default bits"
- to set your own default format pass an option like this:
  "default bits 32".
- this option affects subsequent calls to Console::open.


#3. Are there any options that are missing?
-------------------------------------------

Do you need control over something that is not listed above?
If so, post a request to news.scene.org/coders.ptc.development
and we will see what we can do about it right away.
