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