Added shadow mask feature, which allows selective shadow casting by different lights.

Documented multithreading.

Docs/Reference.dox

@@ -48,6 +48,7 @@ Any Object can be registered to the Context as a subsystem, by using the functio
 After Engine initialization, the following subsystems will always exist:
 
 - Time: manages frame updates, frame number and elapsed time counting, and controls the frequency of the operating system low-resolution timer.
+- WorkQueue: executes background tasks in worker threads.
 - FileSystem: provides directory operations.
 - Log: provides logging services.
 - ResourceCache: loads resources and keeps them cached for later access.
@@ -67,7 +68,7 @@ The following subsystems are optional, so GetSubsystem() may return null if they
 - DebugHud: displays rendering mode information and statistics and profiling data. Created by calling \ref Engine::CreateDebugHud "CreateDebugHud()".
 
 In script, the subsystems are available through the following global properties:
-time, fileSystem, log, cache, network, input, ui, audio, engine, graphics, renderer, script, console, debugHud. Note that Profiler is not available to script due to its low-level nature.
+time, fileSystem, log, cache, network, input, ui, audio, engine, graphics, renderer, script, console, debugHud. Note that WorkQueue and Profiler are not available to script due to their low-level nature.
 
 
 \page Events Events
@@ -373,7 +374,7 @@ When setting the initial screen mode, Graphics does a few checks:
 
 - For Direct3D9, the supported shader model is checked. 2.0 is minimum, but 3.0 will be used if available. %Shader model 2.0 can be forced by calling \ref Graphics::SetForceSM2() "SetForceSM2()".
 - For OpenGL, version 2.0 with EXT_framebuffer_object and EXT_packed_depth_stencil extensions is checked for.
-- Are hardware shadow maps supported? Both ATI & NVIDIA style shadow maps can be used. If neither are available, a fallback mode using a color texture and  minimal shadow filtering will be chosen instead.
+- Are hardware shadow maps supported? Both ATI & NVIDIA style shadow maps can be used. If neither are available, a fallback mode using a color texture and minimal shadow filtering will be chosen instead.
 
 \section Rendering_Renderer Renderer
 
@@ -417,7 +418,7 @@ The rendering-related components defined by the %Graphics library are:
 
 The following techniques will be used to reduce the amount of CPU and GPU work when rendering. By default they are all on:
 
-- Software rasterized occlusion: after the octree has been queried for visible objects, the objects that are marked as occluders are rendered on the CPU to a small hierarchical-depth buffer, and it will be used to test the non-occluders for visibility. Occlusion will also be used to optimize away directional light shadow casters that are behind another shadow caster. Use \ref Renderer::SetMaxOccluderTriangles() "SetMaxOccluderTriangles()" and \ref Renderer::SetOccluderSizeThreshold() "SetOccluderSizeThreshold()" to configure the occlusion rendering.
+- Software rasterized occlusion: after the octree has been queried for visible objects, the objects that are marked as occluders are rendered on the CPU to a small hierarchical-depth buffer, and it will be used to test the non-occluders for visibility. Use \ref Renderer::SetMaxOccluderTriangles() "SetMaxOccluderTriangles()" and \ref Renderer::SetOccluderSizeThreshold() "SetOccluderSizeThreshold()" to configure the occlusion rendering.
 
 - Hardware instancing (Direct3D9 SM3.0 only): rendering operations with the same geometry, material and light will be grouped together and performed as one draw call. Objects with a large amount of triangles will not be rendered as instanced, as that could actually be detrimental to performance. Use \ref Renderer::SetMaxInstanceTriangles() "SetMaxInstanceTriangles()" to set the threshold. Note that even when instancing is not available, or the triangle count of objects is too large, they still benefit from the grouping, as render state only needs to be set once before rendering each group, reducing the CPU cost.
 
@@ -569,6 +570,12 @@ Additionally there are shadow fade distance, shadow intensity, shadow resolution
 
 Finally, there are global settings for the shadow map base resolution and shadow map depth (16 or 24 bit) & filtering quality (1 or 4 samples) in Renderer.
 
+\section Lights_ShadowCulling Shadow culling
+
+Similarly to light culling with lightmasks, shadowmasks can be used to select which objects should cast shadows with respect to each light. See \ref Drawable::SetShadowMask "SetShadowMask()". A potential shadow caster's shadow mask will be ANDed with the light's lightmask to see if it should be rendered to the light's shadow map. Also, when an object is inside a zone, its shadowmask will be ANDed with the zone's shadowmask as well. By default all bits are set in the shadowmask.
+
+For an example of shadow culling, imagine a house (which itself is a shadow caster) containing several objects inside, and a shadowed directional light shining in from the windows. In that case shadow map rendering can be avoided for objects already in shadow by clearing the respective bit from their shadowmasks.
+
 \section Lights_ShadowMapReuse Shadow map reuse
 
 The Renderer can be configured to either reuse shadow maps, or not. To reuse is the default, use \ref Renderer::SetReuseShadowMaps "SetReuseShadowMaps()" to change.
@@ -1069,6 +1076,19 @@ For safety, allowed remote event types should be registered so that a client can
 
 Like with ordinary events, in script event types are strings instead of name hashes for convenience.
 
+
+\page Multithreading Multithreading
+
+Urho3D uses a task-based multithreading model. The WorkQueue subsystem can be supplied with tasks described by the WorkItem structure, by calling \ref WorkQueue::AddWorkItem "AddWorkItem()". These will be executed in background worker threads. The function \ref WorkQueue::Complete "Complete()" will complete all currently pending tasks, and execute them also in the main thread to make them finish faster.
+
+On single-core systems no worker threads will be created. In the presence of more cores, worker threads will be created up to a maximum of four. Two cores will be preferably left free to allow one for the main thread, and another for the GPU driver and audio processing.
+
+The work items include a function pointer to call, with the signature "void WorkFunction(const WorkItem* item, unsigned threadIndex)." The thread index ranges from 0 to n, where 0 represents the main thread and n is the number of worker threads created. Its function is to aid in splitting work into per-thread data structures that need no locking. The work item also contains three void pointers: start, end and aux, which can be used to describe a range of sub-work items, and an auxiliary data structure, which may for example be the object that originally queued the work.
+
+Multithreading is so far not exposed to scripts, and is currently used only in a limited manner: to speed up the preparation of rendering views including lit object and shadow caster queries, occlusion tests, particle system updates and animation and skinning updates. Raycasts into the Octree are also threaded, but physics raycasts are not.
+
+Note that as the Profiler currently manages only a single hierarchy tree, profiling blocks may only appear in main thread code, not in the work functions.
+
 \page Tools Tools
 
 \section Tools_AssetImporter AssetImporter

Docs/ScriptAPI.dox

@@ -1589,6 +1589,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1651,6 +1652,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1703,6 +1705,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1744,6 +1747,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1785,6 +1789,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1854,6 +1859,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -1962,6 +1968,7 @@ Properties:<br>
 - float lodBias
 - uint viewMask
 - uint lightMask
+- uint shadowMask
 - uint zoneMask
 - uint maxLights
 - BoundingBox& worldBoundingBox (readonly)
@@ -2117,7 +2124,6 @@ Properties:<br>
 - uint[] numLights (readonly)
 - uint[] numShadowMaps (readonly)
 - uint[] numOccluders (readonly)
-- uint[] numShadowOccluders (readonly)
 
 
 Input

Docs/Urho3D.dox

@@ -31,6 +31,7 @@ For further reference, see:
 \ref UI "User interface" <br>
 \ref Serialization "Serialization" <br>
 \ref Network "Networking" <br>
+\ref Multithreading "Multithreading" <br>
 \ref Tools "Tools" <br>
 \ref FileFormats "Custom file formats" <br>
 \ref CodingConventions "Coding conventions" <br>

Engine/Engine/APITemplates.h

@@ -628,6 +628,8 @@ template <class T> void RegisterDrawable(asIScriptEngine* engine, const char* cl
     engine->RegisterObjectMethod(className, "uint get_viewMask() const", asMETHOD(T, GetViewMask), asCALL_THISCALL);
     engine->RegisterObjectMethod(className, "void set_lightMask(uint)", asMETHOD(T, SetLightMask), asCALL_THISCALL);
     engine->RegisterObjectMethod(className, "uint get_lightMask() const", asMETHOD(T, GetLightMask), asCALL_THISCALL);
+    engine->RegisterObjectMethod(className, "void set_shadowMask(uint)", asMETHOD(T, SetShadowMask), asCALL_THISCALL);
+    engine->RegisterObjectMethod(className, "uint get_shadowMask() const", asMETHOD(T, GetShadowMask), asCALL_THISCALL);
     engine->RegisterObjectMethod(className, "void set_zoneMask(uint)", asMETHOD(T, SetZoneMask), asCALL_THISCALL);
     engine->RegisterObjectMethod(className, "uint get_zoneMask() const", asMETHOD(T, GetZoneMask), asCALL_THISCALL);
     engine->RegisterObjectMethod(className, "void set_maxLights(uint)", asMETHOD(T, SetMaxLights), asCALL_THISCALL);

Engine/Graphics/Drawable.cpp

@@ -45,6 +45,7 @@ Drawable::Drawable(Context* context) :
     lodBias_(1.0f),
     viewMask_(DEFAULT_VIEWMASK),
     lightMask_(DEFAULT_LIGHTMASK),
+    shadowMask_(DEFAULT_SHADOWMASK),
     zoneMask_(DEFAULT_ZONEMASK),
     maxLights_(0),
     distance_(0.0f),
@@ -74,6 +75,7 @@ void Drawable::RegisterObject(Context* context)
     ATTRIBUTE(Drawable, VAR_INT, "Max Lights", maxLights_, 0, AM_DEFAULT);
     ATTRIBUTE(Drawable, VAR_INT, "View Mask", viewMask_, DEFAULT_VIEWMASK, AM_DEFAULT);
     ATTRIBUTE(Drawable, VAR_INT, "Light Mask", lightMask_, DEFAULT_LIGHTMASK, AM_DEFAULT);
+    ATTRIBUTE(Drawable, VAR_INT, "Shadow Mask", shadowMask_, DEFAULT_SHADOWMASK, AM_DEFAULT);
     ACCESSOR_ATTRIBUTE(Drawable, VAR_INT, "Zone Mask", GetZoneMask, SetZoneMask, unsigned, DEFAULT_ZONEMASK, AM_DEFAULT);
 }
 
@@ -132,6 +134,11 @@ void Drawable::SetLightMask(unsigned mask)
     lightMask_ = mask;
 }
 
+void Drawable::SetShadowMask(unsigned mask)
+{
+    shadowMask_ = mask;
+}
+
 void Drawable::SetZoneMask(unsigned mask)
 {
     zoneMask_ = mask;

Engine/Graphics/Drawable.h

@@ -34,6 +34,7 @@ static const unsigned DRAWABLE_ZONE = 0x4;
 static const unsigned DRAWABLE_ANY = 0xff;
 static const unsigned DEFAULT_VIEWMASK = M_MAX_UNSIGNED;
 static const unsigned DEFAULT_LIGHTMASK = M_MAX_UNSIGNED;
+static const unsigned DEFAULT_SHADOWMASK = M_MAX_UNSIGNED;
 static const unsigned DEFAULT_ZONEMASK = M_MAX_UNSIGNED;
 static const int DRAWABLES_PER_WORK_ITEM = 16;
 
@@ -115,11 +116,13 @@ public:
     void SetShadowDistance(float distance);
     /// %Set LOD bias.
     void SetLodBias(float bias);
-    /// %Set view mask. Will be and'ed with camera's view mask to see if the object should be rendered.
+    /// %Set view mask. Is and'ed with camera's view mask to see if the object should be rendered.
     void SetViewMask(unsigned mask);
-    /// %Set light mask. Will be and'ed with light's and zone's light mask to see if the object should be lit.
+    /// %Set light mask. Is and'ed with light's and zone's light mask to see if the object should be lit.
     void SetLightMask(unsigned mask);
-    /// %Set zone mask. Will be and'ed with zone's zone mask to see if the object should belong to the zone.
+    /// %Set shadow mask. Is and'ed with light's light mask and zone's shadow mask to see if the object should be rendered to a shadow map.
+    void SetShadowMask(unsigned mask);
+    /// %Set zone mask. Is and'ed with zone's zone mask to see if the object should belong to the zone.
     void SetZoneMask(unsigned mask);
     /// %Set maximum number of lights. Default 0 is unlimited.
     void SetMaxLights(unsigned num);
@@ -146,6 +149,8 @@ public:
     unsigned GetViewMask() const { return viewMask_; }
     /// Return light mask.
     unsigned GetLightMask() const { return lightMask_; }
+    /// Return shadow mask.
+    unsigned GetShadowMask() const { return shadowMask_; }
     /// Return zone mask.
     unsigned GetZoneMask() const { return zoneMask_; }
     /// Return maximum number of lights.
@@ -222,6 +227,8 @@ protected:
     unsigned viewMask_;
     /// Light mask.
     unsigned lightMask_;
+    /// Shadow mask.
+    unsigned shadowMask_;
     /// Zone mask.
     unsigned zoneMask_;
     /// Maximum lights.
@@ -268,4 +275,3 @@ inline bool CompareDrawables(Drawable* lhs, Drawable* rhs)
 {
     return lhs->GetSortValue() < rhs->GetSortValue();
 }
-

Engine/Graphics/View.cpp

@@ -1157,8 +1157,8 @@ void View::ProcessShadowCasters(LightQueryResult& query, const PODVector<Drawabl
         if (maxShadowDistance > 0.0f && drawable->GetDistance() > maxShadowDistance)
             continue;
         
-        // Check light mask
-        if (!(GetLightMask(drawable) & light->GetLightMask()))
+        // Check shadow mask
+        if (!(GetShadowMask(drawable) & light->GetLightMask()))
             continue;
         
         // Project shadow caster bounding box to light view space for visibility check
@@ -1656,6 +1656,11 @@ unsigned View::GetLightMask(Drawable* drawable)
     return drawable->GetLightMask() & GetZone(drawable)->GetLightMask();
 }
 
+unsigned View::GetShadowMask(Drawable* drawable)
+{
+    return drawable->GetShadowMask() & GetZone(drawable)->GetShadowMask();
+}
+
 Technique* View::GetTechnique(Drawable* drawable, Material*& material)
 {
     if (!material)

Engine/Graphics/View.h

@@ -159,6 +159,8 @@ private:
     Zone* GetZone(Drawable* drawable);
     /// Return the drawable's light mask, considering also its zone.
     unsigned GetLightMask(Drawable* drawable);
+    /// Return the drawable's shadow mask, considering also its zone.
+    unsigned GetShadowMask(Drawable* drawable);
     /// Return material technique, considering the drawable's LOD distance.
     Technique* GetTechnique(Drawable* drawable, Material*& material);
     /// Check if material should render an auxiliary view (if it has a camera attached.)

Engine/Graphics/Zone.cpp

@@ -64,6 +64,7 @@ void Zone::RegisterObject(Context* context)
     ATTRIBUTE(Zone, VAR_BOOL, "Override Mode", override_, 0, AM_DEFAULT);
     ATTRIBUTE(Zone, VAR_INT, "Priority", priority_, 0, AM_DEFAULT);
     ATTRIBUTE(Zone, VAR_INT, "Light Mask", lightMask_, DEFAULT_LIGHTMASK, AM_DEFAULT);
+    ATTRIBUTE(Zone, VAR_INT, "Shadow Mask", shadowMask_, DEFAULT_SHADOWMASK, AM_DEFAULT);
     ACCESSOR_ATTRIBUTE(Zone, VAR_INT, "Zone Mask", GetZoneMask, SetZoneMask, unsigned, DEFAULT_ZONEMASK, AM_DEFAULT);
 }