OpenPTC 1.0 Win32 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.

NOTE: options in a merged distribution behave in a slightly
different way to normal. If you want to pass options BEFORE
the console is opened, you have to manually specify which
console the options are directed to. In the case of this
distribution, you have to choose "DirectX" for the console
options listed below like this:

    // create console
    Console console;

    // set console options
    console.option("DirectX");             // this is required!
    console.option("fullscreen output");
    console.option("default width 640");
    console.option("default height 480");

    // open console
    console.open(...);


#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 most 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 most implementations of PTC
  thanks to the HERMES library (http://hermes.terminal.at).


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

"default output"
- tells the console to use the default output mode, which
  normally involves attempting fullscreen first (if applicable)
  then falling back down to windowed output if fullscreen is
  not possible.
- this option affects subsequent calls to Console::open.
- this is, strangely enough, set by default :)
- ... however, in debug build, PTC for Win32 has "windowed output" 
  set initially instead of "default output". This is because
  fullscreen output is next to impossible to debug under ddraw.

"windowed output"
- this forces the console to attempt to open the display in
  windowed output mode instead of first trying fullscreen, then
  falling back to windowed.
- this option affects subsequent calls to Console::open.

"fullscreen output"
- this forces the console to open the display in fullscreen mode
  and if fullscreen is not possible, it fails immediately instead
  of falling back to windowed output.
- this option affects subsequent calls to Console::open.

"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 provides 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.

"resizable window"
- this option makes the window created in console open resizable
  when the console is opened in windowed output.
- this option is set by default.
- this option affects subsequent calls to Console::open.

"fixed window"
- this option makes the window created in console open fixed size
  (non-resizable) when the console is opened in windowed output.
- this option affects subsequent calls to Console::open.

"windowed primary direct"
- this option sets up direct writing to the primary surface in
  windowed output.
- use this option with care! writing directly to the primary
  surface in windowed output can cause problems!
- this option affects subsequent calls to Console::open.

"windowed primary secondary"
- this option sets up a secondary surface to be written to
  and then copied to the primary surface.
- this fixes problems with direct primary writes in windowed
  mode.
- this option is set by default because its the best way to
  write to the primary in windowed output.
- this option affects subsequent calls to Console::open.

"fullscreen primary direct"
- this option sets up direct writing to the primary surface in
  fullscreen output.
- this is set by default as it is typically the best way to
  write to the primary surface in fullscreen output.
- this option affects subsequent calls to Console::open.

"fullscreen primary secondary"
- this options sets up a secondary surface to be written to
  and then copied to the primary surface on each update.
- this option is not set by default.
- this option affects subsequent calls to Console::open.

"center window"
- this option turns window centering on for windowed output.
  it has no effect on fullscreen output.
- it will NOT center an already open console, to do this
  use the Console::window extension to get the HWND and
  use SetWindowPos to move the window.
- this option is not set by default.
- this option affects subsequent calls to Console::open.

"default window position"
- this option turns window centering off, instead letting
  windows decide what the best position for the window is.
- this option is set by default.
- this option and the "center window" option cancel each
  other out.
- this option affects subsequent calls to Console::open.

"synchronized update"
- this option hints that the Console::update should attempt
  to synchronize the the vertical retrace.
- this option is set by default.
- this option affects subsequent calls to Console::open.

"unsynchronized update"
- this option hints that the Console::update should not
  synchronize to the vertical retrace.
- it is only a hint, and in many cases synchronization
  to the vertical retrace is always enabled (fullscreen
  output with flip is always synchronized...), and in
  some other cases, synchronization is not supported
  (often sync is not supported for windowed output..)
- the only place where this option currently has effect
  is in windowed output where a secondary surface is
  blitted to the primary. this option determines whether
  or not that blt is scheduled to occur during retrace.
- this option is not set by default.
- this option affects subsequent calls to Console::open.

"default nearest"
- This option sets the nearest mode matching method to
  the default: stretching if supported in hardware,
  centering otherwise.
- this option is set by default.
- this option affects subsequent calls to Console::open.

"center nearest"
- This option setes the nearest mode matching method
  to centering.
- Centering is always supported in hardware, and may be
  faster than stretching, even if the stretching is
  supported by hardware.
- this option affects subsequent calls to Console::open.

"stretch nearest"
- This option setes the nearest mode matching method
  to stretching.
- Stretching is not always supported in hardware, and if
  you force PTC to stretch when the hardware does not
  support it, it will go very VERY slow! beware!
- this option affects subsequent calls to Console::open.


"default cursor"
- This option sets the cursor mode to default. This means
  that the cursor will be hidden in fullscreen and shown
  in windowed output.
- This is set by default.
- this option affects subsequent calls to Console::open.

"show cursor"
- This option forces the cursor to be shown in both fullscreen
  and windowed output.
- this option affects subsequent calls to Console::open.

"hide cursor"
- This option forces the cursor to be hidden in both fullscreen
  and windowed output.
- this option affects subsequent calls to Console::open.

"frequency [n]"
- This option sets the frequency of the display mode to be
  opened.
- The frequency is only a hint, if the requested frequency
  does not exist an error may be thrown, or it may be ignored
  by the driver.
- The parameter 'n' is frequency in hertz. To open a display
  with 60hz refresh rates, use the option "frequency 60".
- Omitting the parameter 'n' sets the frequency back to default
- 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.
