Sword of Moonlight Extension Library/window extensions

directx_version_to_use_for_window

Introduced around 1.0.0.1, this extension conveys the version of Direct3D desired for visual presentation stuff. The version is in terms of DirectX versions. Originally this extension defaulted to DirectX 7, however for some time it will only accept 7, which is not recommended since it is very poorly maintained. 7 was used by Sword of Moonlight's original programming (the tools actually use 6, but that does not apply to this section of the INI file.)

9 is the de factor native mode of SomEx. However it too is poorly maintained when forced to operate with the default shaders or DirectX 9's "fixed function" implementation. There simply isn't enough time to devote to backward compatibility modes with the (single person) staff on hand. Just leave this and #shader_compatibility_mode alone unless you have a good reason for doing otherwise. Values are limited to positive whole numbers.[#]

do_auto_pause_window_while_inactive

Introduced around 1.0.0.1, this extension pauses the game automatically whenever the window loses focus. This is generally speaking a highly recommended extension. Most people will want to use this extension, so if not using it causes problems, chances are no one has noticed! Do not use at your own risk. Values are limited to binary statements.[#]

do_center_picture_for_fixed_display

Introduced around 1.0.0.1, this extension prevents scaling which would be done by your display device. Ideally the picture will end up in the middle of your display at whatever resolution your game is set to. It should have no effect if #do_force_fullscreen_inside_window is on. Values are limited to binary statements.[#]

do_force_fullscreen_inside_window

Introduced around 1.0.0.1, this extension makes your game act like a normal "windowed" application. Changes to resolution will not affect your desktop resolution. If the resolution is less than your desktop resolution in both dimensions it will have a window frame. Otherwise it will be undecorated (frameless) with black mattes filling out negative space.

Authors should probably assume that players will prefer this be the case by default. Values are limited to binary statements.[#]

do_force_immediate_vertical_refresh

Introduced around 1.0.0.1, this extension is the traditional "vsync" disabler. Basically the game will just refresh as soon as it can without regard for the state of the display device. This generally results in tearing which some gamers do not so much mind. Their reward is a generally better frame rate, sometimes a ridiculous frame rate, ie. several times greater than is even humanly perceivable. In which case most frames would never even make it to the display device before being replaced by another. Values are limited to binary statements.[#]

Note: some authors may be tempted to enable this for players in order to ensure the best frame rate for their game. You really really don't want to do this. The effects can be very different for different stations and peoples attitudes. Normally players can use their display adapters control panel to force games to play this way if they want to.

do_force_refresh_on_vertical_blank

Introduced around 1.1.1.3, this extension should guarantee that there is no "tearing" due to the game being out of sync with the display refresh rate. Historically video drivers are supposed to guarantee this, but in reality this has become more or less no longer the case. Therefore this extension is generally speaking highly recommended.

Vista Aero does do a good job of not tearing. This extension is mainly for non-Aero play. The current implementation appears to not affect Aero, therefore authors can probably not worry about turning this on indiscriminately for players.

Your game will probably be slower than it normally would be with this on, because the game must wait for the display's "vertical blank" period in order to proceed. Triple buffering scenarios, if available, may out-mode this extension in the future.

#do_force_immediate_vertical_refresh supersedes this extension. Values are limited to binary statements.[#]

do_not_compromise_fullscreen_mode

Introduced around 1.0.0.1, this extension puts the game in exclusive full screen mode. Like games of yore this is how Sword of Moonlight games originally played. There may or may not be any benefit in playing this way. This is not the default behavior of the Sword of Moonlight Extension Library however, because in modern Microsoft windows environments transitioning into this mode tends to very disruptive; usually meaning your monitor will behave spastically for some moments, and if in Vista "Aero" mode you will be kicked in and out of "Basic" mode. Any background apps wanting your attention will cause serious disruptions, and if something goes wrong you might have to restart your computer. In other words, use this one at your own risk. Values are limited to binary statements.[#]

The Extension Library default behavior is to change the desktop resolution to the game resolution and create a full screen spanning window in which to play in. This feels like a full screen experience and is only slightly disruptive. If you want to have your game at a lower resolution than your desktop but want it to fill the entire display this might be what you want. Otherwise you might want to check out #do_force_fullscreen_inside_window.

Note: in the future there will probably be a maximize button extension for window play which will allow you to stretch the game out without ever changing the desktop resolution.

do_not_hide_window_on_startup

Introduced around 1.1.1.3, this extension will force the window to appear immediately. It makes your game feel more responsive on launch, but is usually not very pretty. The default behavior in window mode (and possibly other modes) is to wait until at least one frame is available before revealing the window.

The only problem is sometimes things don't go right and the window never appears. Ideally this only happens in development scenarios. This extensions ensures that this will not happen, however the window is not guaranteed to be responsive, at least there is a visual indicator that an application is running. Values are limited to binary statements.[#]

do_scale_640x480_modes_to_setting

Introduced around 1.0.0.1, this extension prevents Sword of Moonlight from switching into 640x480 mode for intro screens and movies, and possibly in other types of contexts. This behavior is generally not fun. Especially in full screen mode. Almost needless to say, this extension is highly recommended. Values are limited to binary statements.[#]

do_use_interlaced_scanline_ordering

Introduced around 1.0.0.1, this extension might help if you have an interlaced television, or a display that only supports 1080i and not 1080p. It should only do anything if it does anything at all in exclusive full screen mode. See #do_not_compromise_fullscreen_mode. And it will only work on versions of Windows including Vista and later. It requires Direct3D9Ex support. Values are limited to binary statements.[#]

shader_compatibility_level

Introduced around 1.0.0.1, this extension is used to manually control the kind of shader scenarios which are possible. Generally speaking the settings represent degrees of fallback which a player or author would experience if a given shader is incompatible with their computing environment.

0 will force use of the "fixed function" shading framework. This is basically controlled by drivers. It seeks to emulate versions of Direct3D prior to the wholesale adoption of shaders as the only way to do things.

1 will force generic Ex pixel shaders for versions of Direct3D 9 and up (the default behavior is to use shaders that have been tailored to Sword of Moonlight.)

2 will force generic Ex vertex shaders. 1 uses fixed function vertex shaders. 2 is reserved but not currently implemented. It's equivalent to 1 for the time being.

Any number higher that the last defined level is equivalent to not using this extension. More levels may be staked out in the future. This is not an extension which should be deployed by games, but authors are encouraged to use it in order to see what their games will look like if everything does not go smoothly for the player shader support wise.

This is extension is mainly used by developers in order to work on the fallback shaders. Values are limited to positive whole numbers.[#]

shader_model_to_use

As of 1.2.0.8 there is a bit of a split along shader models, since 2 cannot support the new NPC-style shadows that blend smoothly into terrain and do not stick out into thin air.

Introduced around 1.0.0.1, this extension conveys the desired DirectX "shader model"; see Shader#Models. At present 3 and 2 are available. Support for 1 would be ideal, but due to its highly deprecated nature, this has proved so far elusive. If you set it to a higher model number than what is possible, the next lowest model will be used and so on. In other words, if 3 is not available, 2 will be used if available.

Authors should consider setting this to the highest shader model number with which they are personally familiar. You can set it even higher or leave it unset, but you don't know for sure what the results might be for your game once the higher model numbers becomes available. The default behavior is to start with the highest model number available to the display device.

Generally speaking, built in extensions try to accommodate all models whenever possible. Custom shaders provided by authors or modules are not required to be so rigorous. Authors should test what their games will look like with different shader models. Values are limited to positive whole numbers.[#]

window_title_to_use

Introduced around 1.0.0.1, this extension is the final authority in regards to what will appear in the game window's caption text. If not provided explicitly the Sword of Moonlight Extension Library will try to come up with its own title based on a longish list of candidate places to look. Values are limited to any string of text.[#]