The class bigworld/src/lib/romp/light_map.cpp is generalised to support both the flora and sky light maps. Light maps are configurable in XML files.

22.1.4.1.1. Flora light map

The flora light map details are specified in flora.xml (for details on this file's grammar, see the document File Grammar Guide's section <flora>.xml) and its location is specified in the file resources.xml (for details on this file, see File resources.xml).

The material tag for flora light map should be system/materials/light_map.mfm (for details on this file's grammar, see the document File Grammar Guide's section .mfm).

The default width/height for the flora light map is 64x64. This is small, but still enough resolution for the projection onto the flora, because its visible area is 100x100 metres.

Definition of flora light map

22.1.4.1.2. Sky light map

The sky light map details are specified in the space's sky.xml file, and its location is specified in the space's space.settings file (for details on this file's grammar, see the document File Grammar Guide's section space.settings.).

The material tag for sky light map should be system/materials/sky_light_map.mfm (for details on this file's grammar, see the document File Grammar Guide's section .mfm).

The default width/height for the sky light map is 512x512. This is quite large because the light map is projected across the whole visible world (usually around 1x1 km).

Definition of sky light map

Note

The sky light map can be disabled via the SKY_LIGHT_MAP graphic setting (for details, see Customising options).

When loading texture from disk, it is recommended to have the loading thread running in the background, so that it does not interrupt the rendering thread.

The example below illustrates a texture loader using the BackgroundTask and BGTaskManager classes. Note that the code provides two features — threaded texture loading, and providing the texture to the .fx file system.

#include "pch.hpp"
#include "cstdmf/bgtask_manager.hpp"
#include "cstdmf/concurrency.hpp"

DECLARE_DEBUG_COMPONENT2( "romp", 0 );

// -------------------------------------------------------------------------
// Section: Texture Setter
// -----------------------------------------------------------------------
/**
 *  This class sets textures on the device.  It is also multi-threaded.
 *  When it is told to use a new texture, it uses the background loading thread
 *  to do so.  While it is doing this, the textureName refers to the new
 *  texture, but isLoading() will return true.  And in this state, it will be
 *  sneakily using the pre-existing texture until the new one is ready.
 */
class ThreadedTextureSetter : public Moo::EffectConstantValue
{
public:
  ThreadedTextureSetter():
    pTexture_( NULL ),
    bgLoader_( NULL ),
    textureName_( "" )
  {    
  }
  /**
   *  This method is called by the effect system when a material needs
   *  to draw using a texture with the given automatic semantic.
   */
  bool operator()(ID3DXEffect* pEffect, D3DXHANDLE constantHandle)
  {
    SimpleMutexHolder holder( mutex_ );

    if (pTexture_ && pTexture_->pTexture())
      pEffect->SetTexture(constantHandle, pTexture_->pTexture());
    else
      pEffect->SetTexture(constantHandle, NULL);

    return true;
  }

  /**
   *  This method sets our texture.  If the texture is different then
   *  the existing one, we schedule the new one for loading, and set
   *  the textureName and the isLoading() flag.  In an unspecified amount
   *  of time, the new texture will be loaded and used.
   */
  void texture( const std::string& texName )
  {
    if (textureName_ == texName)
      return;
    
    if (this->isLoading())
      return;
    
    textureName_ = texName;    
    
    bgLoader_ = new BackgroundTask(
            &ThreadedTextureSetter::loadTexture, this,
            &ThreadedTextureSetter::onLoadComplete, this );

#ifndef EDITOR_ENABLED
    BgTaskManager::instance()->addTask( *bgLoader_ );
#else
    ThreadedTextureSetter::loadTexture( this );
    ThreadedTextureSetter::onLoadComplete( this );
#endif
  }

  /**
   *  This class-static method is called by the background loading thread
   *  and allows us to load the texture resource in a blocking manner.
   */
  static void loadTexture( void* s )
  {
    ThreadedTextureSetter* setter = static_cast<ThreadedTextureSetter*>(s);
    Moo::BaseTexturePtr pTex = 
      Moo::TextureManager::instance()->get( setter->textureName() );
    setter->pTexture(pTex);
  }

  /**
   *  This class-static method is called when the background loading thread
   *  has finished.
   */
  static void onLoadComplete( void* s )
  {
    ThreadedTextureSetter* setter = static_cast<ThreadedTextureSetter*>(s);
    setter->onBgLoadComplete();
  }

  /**
   *  This method returns the name of the texture we are currently
   *  drawing with.  If isLoading() is true, then the textureName
   *  refers to the texture we would like to draw with (however we
   *  will be actually drawing with the previous texture ptr).
   */
  const std::string& textureName() const
  {
    return textureName_;
  }

  /**
   *  This method returns true if we are currently waiting for the
   *  background loading thread to load our texture.
   */
  bool isLoading()
  {
    SimpleMutexHolder holder( mutex_ );
    return (bgLoader_ != NULL);
  }

private:
  //only called by the background loading thread
  void pTexture( Moo::BaseTexturePtr pTex )
  {    
    SimpleMutexHolder holder( mutex_ );
    pTexture_ = pTex;    
  }

  //only called by the background loading thread
  void onBgLoadComplete()
  {
    SimpleMutexHolder holder( mutex_ );
    delete bgLoader_;
    bgLoader_ = NULL;
  }

  Moo::BaseTexturePtr pTexture_;
  std::string textureName_;  //store a copy for use while loading.
  BackgroundTask* bgLoader_;  
  SimpleMutex    mutex_;
};

Example of texture loader

To manipulate pixel within a code-generated texture, there are at least two available options:

The closest example on how to achieve this is provided by the flora light map, which uses a variation of the terrain shaders to render the lighting information to a render target. For details, see bigworld/src/lib/romp/flora_light_map.cpp.

Note that to use shaders you will need a video memory/render target surface as described in the section above.

The custom texture is needed to implement the Moo::BaseTexture interface, so that it can add itself to the Texture Manager. However, depending on the following step (applying custom textures to models), you may not even need to use the TextureManager, as it simply provides a 'retrieve texture by name' access to textures.

If you are creating several custom textures for characters, then you may have an internal (hidden) naming scheme, which would result in a minimal benefit for using the texture cache. It may be good enough simply to use smart pointers to handle caching.

Assuming that you have one model that you want display many times, each with a unique custom texture, then you will have to implement a class deriving from the PyFashion class.

Such classes are created from Python, assigned to a PyModel instance, and given an opportunity to alter how a shared model renders (i.e., to set the custom texture on the model). The PyFashion class will become the main interface to your scripts, so in Python you can construct the PyFashion instance with the names of the texture you want to combine, and then assign it to a player's model by simply setting the fashion as any named attribute on its PyModel (PyModel::pySetAttribute automatically detects when a fashion is set on itself, and incorporates it into its rendering chain).

To actually set the custom texture on the model, we recommend creating a class deriving from Moo::EffectConstantValue, and that provides the custom texture to .fx files by name. In the .fx files, use the automatic variable semantic (e.g., Texture diffuseMap :customCharacterTexture), instead of the existing artistEditable property.

For an example code on creating a texture setter, see Loading textures from disk.

Both TEXTURE_QUALITY and TEXURE_COMPRESSION settings are customised by the way of the texture format (.texformat) and detail levels (texture_detail_level.xml) files (for details on this file's grammar, see the document File Grammar Guide's section .texformat).

Lowering the texture quality and using compressed formats helps improving engine performance, by reducing the amount of texture memory required to store them. This means that less data needs to be sent to the graphics card at each frame, ultimately improving frame rate.

TEXURE_QUALITY adjusts the resolution of a texture by preventing its topmost mipmap levels from being loaded. This means that, at the highest level of quality, the texture will be at the same resolution as the original texture map. At medium level, it will be at half its original size, and at a quarter of it at the lowest level of quality.

How many mipmap levels are skipped in each quality level for each texture can be controlled by the lodMode tag in the texture's detailLevel section.

The table below lists the values lodMode can assume, next to the number of mipmaps skipped for each of the texture quality setting levels:

Number of skipped mipmaps per quality setting level/ LOD level

TEXURE_COMPRESSION affects the format in which texture maps are stored in memory. When texture compression is disabled, all textures are stored using the format defined by the format tag in the texture's detailLevel section. When texture compression is enabled, the format defined by the formatCompressed is used. If formatCompressed is not defined for a texture, then format is used, whatever the compression setting is.

Note that there is no restriction to what texture format is used for format or formatCompressed, but for the texture compression setting to yield any significant performance results, formatCompressed should define a texture format that uses less texture memory than its non-compressed format counterpart.

For details on how to setup a texture's level of detail, see Texture detail levels/compression. For details on the configuration file's grammar, see the document File Grammar Guide's section .texformat.

SHADOWS_COUNT defines the maximum number of simultaneous dynamic entity shadow casters in a scene.

Shadows are rendered using shadow buffers, thus consuming texture memory. Filling the buffers up at every frame requires rendering the scene again for each shadow caster. Reducing the number of simultaneous dynamic shadow casters reduces the memory requirements and the amount of processing used to update the buffers at every frame.

Value ranges from 1 to value specified in maxCount shadows.xml file, in power of two steps (defined in shadows.xml — for details on this file's grammar, see the document File Grammar Guide's section shadows.xml).

FLORA_DENSITY defines the size of the vertex buffer used to render the flora detail objects.

Since the flora drawing distance to the camera is fixed, defining the size of the vertex buffer also determines the flora density. Because it uses alpha blending, drawing the flora can negatively influence the frame rendering time, especially on hardware with limited fill rate performance. Reducing the amount of flora rendered at any one time may help improving the frame rate.

Flora density options are defined in <graphics_settings>.xml (for details on this file's grammar, see the document File Grammar Guide's section <graphics_settings>.xml) as a multiplier of the vertex buffer, which actual size is defined per space in <flora>.xml (for details on this file's grammar, see the document File Grammar Guide's section <flora>.xml).

<graphics_settings.xml>

  <flora>
    <option>
      <label>  HIGH </label>
      <value>  1.0  </value>
    </option>

    <option>
      <label>  LOW  </label>
      <value>  0.5  </value>
    </option>

    <option>
      <label>  OFF  </label>
      <value>  0    </value>
    </option>
  </flora>

</graphics_settings.xml>

Example <graphics_settings>.xml — Configuring flora density

FAR_PLANE defines the maximum viewing distance when rendering the 3D world.

Decreasing the viewing distance reduces the amount of geometry sent to the rendering pipeline, resulting in higher frame rates.

Because the far plane distance can be defined on a per-space basis (in space.settings file — for details on this file's grammar, see the document File Grammar Guide's section space.settings), FAR_PLANE is actually multiplied by the space's specific far plane value before it is applied to the camera.

Specified in <graphics_settings>.xml (for details on this file's grammar, see the document File Grammar Guide's section <graphics_settings>.xml), the far plane can be configured as in the example below:

<graphics_settings.xml>

  <farPlane>

    <option>
      <value>  1.0     </value>
      <label>  FAR     </label>
    </option>

    <option>
      <value>  0.75    </value>
      <label>  MEDIUM  </label>
    </option>

    <option>
      <value>  0.5     </value>
      <label>  NEAR    </label>
    </option>

  </farPlane>

</graphics_settings.xml>

Example <graphics_settings>.xml — Configuring far plane

OBJECT_LOD defines the relative distance to the camera before LOD transitions occur.

For standard BigWorld models, LOD distances are defined using the Model Editor. Particle Editor is used to set the LOD distance for particle systems (the maximum distance to which the system is still visible). LOD levels and transition distances for SpeedTrees are defined inside SpeedTreeCAD (although they can be overridden by the SpeedTree's XML configuration file, which is specified in resources.xml file's speedTreeXML tag. For details on this file, see File resources.xml).

The OBJECT_LOD setting specify multipliers that will modify those distances during runtime, allowing the user to trade some visual quality for better performance.

The LOD multipliers are defined in <graphics_settings>.xml (for details on this file's grammar, see the document File Grammar Guide's section <graphics_settings>.xml):

<graphics_settings.xml>

  <objectLOD>

    <option>
      <value>  1.0     </value>
      <label>  HIGH   </label>
    </option>

    <option>
      <value>  0.66    </value>
      <label>  MEDIUM  </label>
    </option>

    <option>
      <value>  0.33    </value>
      <label>  LOW     </label>
    </option>

  </objectLOD>

</graphics_settings.xml>

Example <graphics_settings>.xml — Configuring object LOD

Auto-detecting of settings is supported through an xml configuration file specified by the tag graphicsSettingsPresets in resources.xml. This file defines matching criteria to attempt to match a group of settings to a specific device (graphics card). There are three different ways of matching a group of settings to a device. All matching is done against the D3DADAPTER_IDENTIFIER9 structure. The auto-detection itself is performed in the method Moo::GraphicsSetting::init

<graphicsPreferences> HIGH <=== Name of the preset, if no name is present, the preset will not appear in the list of settings, 
                                but it will still be used when auto-detecting settings for the graphics card

  <entry> <=== a graphics setting to change 
    <label> CLASSIC_TERRAIN_QUALITY </label> <=== the name of the graphics setting
    <activeOption> 0 </activeOption> <===the selected option
  </entry>

  <GUIDMatch>  01234567.89abcdef.01234567.89abcdef </GUIDMatch>  
    <===  Combined GUID of device and driver version, this is the value from DeviceIdentifier in the 
          D3DADAPTER_IDENTIFIER9 structure saved out using the BigWorld UniqueID class.
          If this value matches, the setting will be used.

  <VendorDeviceIDMatch>
    <VendorID> 4318 </VendorID> <=== the VendorId from D3DADAPTER_IDENTIFIER9
    <DeviceID> 1554 </DeviceID> <=== the DeviceId from D3DADAPTER_IDENTIFIER9
  </VendorDeviceIDMatch> <=== If these two values match the current device, the setting will be selected
                              unless there is a GUIDMatch with the current device

  <DeviceDescriptionMatch> 
    <string> nvidia </string> <=== Any number of strings that will be matched against the 
    <string> 6800 </string> <=== Description property from D3DADAPTER_IDENTIFIER9
  </DeviceDescriptionMatch>  <=== If these values match the current device, the setting will be selected
                                  unless there is a GUIDMatch or VendorDeviceIDMatch with the 
                                  current device

  <defaultSetting> true </defaultSetting> <=== this value is true for the value to be used as the default setting,
                                               the default setting is used when no other settings match.
</graphicsPreferences>

Example <graphics_settings_presets>.xml — Setting up device matches

A simple python graphics presets class is also supplied. This class helps with grouping several graphics settings together so that you can have pre-defined settings for multiple graphics options for a specific level of hardware or performance. The GraphicsPresets class can be found in the folder bigworld/res/scripts/GraphicsPresets.py.

Most settings take effect immediately after calling BigWorld.setGraphicsSettings, but some are just flagged as delayed. That means that after being set they are added to a list of pending settings, and that they will only come into effect when that list gets committed.

This was designed to give the interface programmer a chance to warn the user that processing the new settings may take a while to complete before the client application blocks for a few seconds (currently, there is no support for displaying a progress bar while the settings are being processed).

The following functions allow the scripts to manage the pending settings list:

Some settings are not applied until the client application is restarted. The function BigWorld.graphicsSettingsNeedRestart returns true whenever the client requires a restart for a recently changed setting to take effect.

The size of the back buffer can be changed (via Debug (Watchers) Console) by the backBufferWidthOverride watcher.

The values specified to the watcher, and their effect on the back buffer are described below:

To take a high-resolution screenshot

The list below describes some errors that you might come across when taking high-resolution screenshots and how to solve them:

To produce high-resolution screenshots, a very capable video card is necessary — the two key requirements are:

DirectX 9 requires 2048 resolution as a minimum, but 4096 is available on nVidia GeForce3+ (7800+ recommended) and ATI 1X800+ series cards. It is recommended that you have a minimum of 256MB video memory when taking screenshots at resolutions in the order of 4096x3072.