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. It will default to 7 if the number used is incompatible. The recommended setting however is 9, for DirectX/3D 9. 7 is like a safe-mode; graphical extensions are not always implemented or even feasible in 7 mode, and 7 is more likely to have bugs or outstanding issues, because generally speaking it's only ever worked with for completeness sake.

7 is considered an obsolete technology but will likely remain the default for the foreseeable future because it is what Sword of Moonlight uses, and therefore requires the least amount of modification to make things work, and is therefore technically safer, though not necessarily more likely to be glitch free. Values are limited to positive whole numbers.

Other versions may work with debug builds (not normally/easily available to the public) for research and development purposes.

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.[#]

restrict_aspect_ratio_to

Introduced around 1.0.0.1, this extension restricts the aspect ratio, for example 4:3 for standard definition, and 13:9 for (high definition) widescreen. Historically this was used because Sword of Moonlight was designed with 4:3 in mind, and exhibits visual artifacts in any other mode - some even with 4:3 pictures. You can now however use #do_fov and #do_fix_fov_in_memory to eliminate these artifacts, so there's probably no reason to ever use 4:3 again!

The future of this extension is likely to include 13:9 if and when an author desires to build their game strictly around a 720 or 1080 presentation. You might want to do this in order to synchronize movies with in the game visuals or just because your desire total control over how your audience will experience your work. Values are limited to the text string, 4:3.

restrict_frame_rate_to

This extension is currently unimplemented. Once ready it will set a hard speed limit for frame rates.

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

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.

Markup is allowed in this title. As of SomEx.dll ver. 1.0.0.1 only <fps/> is supported. For example, wherever <fps/> appears in the title the current (averaged) frame rate (frames per second) will be printed instead. The plan for the future is to add some basic stats so a player could play without any "heads up display" elements if so desired. Values are limited to any string of text.[#]