# Windows Options

###
Introduction

Options strings give users of an OpenPTC 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 several implementations of OpenPTC, but most apply to only a specific implementation.
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. "ptc.cfg" is just a plain text file in which each line is passed to the console as an option string.
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(...);

###
Options that apply to both surfaces and consoles

#### "enable dithering"

- Enables dithering when copying from this surface or console to another surface.
- Dithering is disabled by default because it is generally slower than pixel format conversion without dithering.
- This option is only a hint, dithering will be enabled if it is implemented for this conversion and dithering makes sense in this case (ie. 32 bit to 16 bit makes sense, but 16 bit to 32 bit does not).
- This option is supported on most implementations of OpenPTC thanks to the HERMES library.

#### "disable dithering"

- Disables dithering when copying from this surface or console to another surface.
- Dithering is disabled by default because it is generally slower than pixel format conversion without dithering.
- This option is supported on most implementations of OpenPTC thanks to the HERMES library.

###
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 is 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 DirectX.
- This option affects subsequent calls to Console::open.

#### "windowed output"

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

#### "default 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.
- To set your own default width pass an option like this: "default width 640".
- The parameter 'n' is optional, if it is omitted, the width is set back to the original default width: "default width".
- 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.
- To set your own default height pass an option like this: "default height 640".
- The parameter 'n' is optional, if it is omitted, the height is set back to the original default height: "default height".
- 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).
- To set your own default format pass an option like this: "default bits 32".
  The parameter 'n' is optional, if it is omitted, the format is set back to the original default format. ie. "default bits"
- 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.

#### "resizable window"

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

#### "fixed window"

- This 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.

#### "center window"

- This option turns window centering on for windowed output.
- It has no effect on fullscreen output.
- Warning! 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 to the center.
- This option affects subsequent calls to Console::open.

#### "default window position"

- This option turns window centering off, letting windows decide what the best position for the window is.
- This is set by default.
- This option and the "center window" option cancel each other out.
- 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.
- It 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, only enable it if for some reason you want to force the console to create a secondary surface.
- This option affects subsequent calls to Console::open.

#### "synchronized update"

- This option hints that the Console::update should attempt to synchronize the to the vertical retrace.
- This 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. It determines whether or not that blt is scheduled to occur during retrace.
- This option affects subsequent calls to Console::open.

#### "default nearest"

- This option sets the nearest mode matching method to the default, which currently is centering.
- This 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 more likely to be supported by hardware, and is usually much faster than stretching.
- 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 stretching when the hardware does not support it, it will be 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, and as of version 1.0.18 may be used to control the cursor of an open console.

#### "show cursor"

- This option forces the cursor to be shown in both fullscreen and windowed output.
- This option affects subsequent calls to Console::open, and as of version 1.0.18 may be used to control the cursor of an open console.

#### "hide cursor"

- This option forces the cursor to be hidden in both fullscreen and windowed output.
- This option affects subsequent calls to Console::open, and as of version 1.0.18 may be used to control the cursor of an open console.

#### "enable key buffering"

- This option enables buffering of keyboard events that come in to the console via WM_KEYDOWN.
- Buffering of keyboard events is required for the correct operation of Console::key and Console::read.
- This option is set by default.
- You may only set this option while the console is open, it will have no effect if the console is closed.

#### "disable key buffering"

- This option disables buffering of keyboard events that come in to the console via WM_KEYDOWN.
- Buffering of keyboard events is required for the correct operation of Console::key and Console::read, however in some circumstances these functions are not required, for instance when you are managing your own HWND you typically dont need key buffering because you can access WM_KEYDOWN directly.
- See the "WndProc" example in the "Extensions" directory for an example of disabling key buffering.
- This option is not set by default.
- You may only set this option while the console is open, it will have no effect if the console is closed.

#### "enable logging"

- This option enables logging of all internal messages and errors thrown during execution.
- Useful for debugging, it is enabled by default in debug build, disabled in release build.
- All data is logged to the file 'ptc.log' in the current working directory when logging is enabled.
- Note that sometimes errors are thrown and caught in normal program flow. Dont be worried if the ptc.log has errors in it, that does not mean there are bugs :)
- This option may be called at any time, whether or not the console is open.

#### "disable logging"

- This option disables error logging.
- By default error logging is disabled in release build, and enabled in debug build.
- You can set this option at any time, whether or not the console is open.

#### "enable blocking"

- Enables blocking when the application looses focus.
- Blocking is enabled by default in fullscreen output, and direct to primary windowed output (rare).
- In normal windowed output, blocking has been disabled so that rendering continues when the application loses focus.
- You may only set this option while the console is open, it will have no effect if the console is closed.

#### "disable blocking"

- Disables console blocking when an application loses focus.
- Use this option only if you really know what you are doing.
- Blocking is required for correct operation of fullscreen output and direct primary output in windowed mode.
- Set this option while the console is open.