urho3d/Engine/Scene/Scene.h

//
// Urho3D Engine
// Copyright (c) 2008-2012 Lasse Öörni
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
//

#pragma once

#include "Mutex.h"
#include "Node.h"
#include "SceneResolver.h"
#include "XMLElement.h"

class File;
class PackageFile;

static const unsigned FIRST_REPLICATED_ID = 0x1;
static const unsigned LAST_REPLICATED_ID = 0xffffff;
static const unsigned FIRST_LOCAL_ID = 0x01000000;
static const unsigned LAST_LOCAL_ID = 0xffffffff;

/// Asynchronous loading progress of a scene.
struct AsyncProgress
{
    /// File for binary mode.
    SharedPtr<File> file_;
    /// XML file for XML mode.
    SharedPtr<XMLFile> xmlFile_;
    /// Current XML element for XML mode.
    XMLElement xmlElement_;
    /// Loaded root-level nodes.
    unsigned loadedNodes_;
    /// Total root-level nodes.
    unsigned totalNodes_;
};

/// Root scene node, represents the whole scene.
class Scene : public Node
{
    OBJECT(Scene);
    
    using Node::GetComponent;
    using Node::SaveXML;
    
public:
    /// Construct.
    Scene(Context* context);
    /// Destruct.
    virtual ~Scene();
    /// Register object factory. Node must be registered first.
    static void RegisterObject(Context* context);
    
    /// Load from binary data. Return true if successful.
    virtual bool Load(Deserializer& source);
    /// Save to binary data. Return true if successful.
    virtual bool Save(Serializer& dest);
    /// Load from XML data. Return true if successful.
    virtual bool LoadXML(const XMLElement& source);
    
    /// Load from an XML file. Return true if successful.
    bool LoadXML(Deserializer& source);
    /// Save to an XML file. Return true if successful.
    bool SaveXML(Serializer& dest);
    /// Load from a binary file asynchronously. Return true if started successfully.
    bool LoadAsync(File* file);
    /// Load from an XML file asynchronously. Return true if started successfully.
    bool LoadAsyncXML(File* file);
    /// Stop asynchronous loading.
    void StopAsyncLoading();
    /// Instantiate scene content from binary data. Return root node if successful.
    Node* Instantiate(Deserializer& source, const Vector3& position, const Quaternion& rotation, CreateMode mode = REPLICATED);
    /// Instantiate scene content from XML data. Return root node if successful.
    Node* InstantiateXML(const XMLElement& source, const Vector3& position, const Quaternion& rotation, CreateMode mode = REPLICATED);
    /// Instantiate scene content from XML data. Return root node if successful.
    Node* InstantiateXML(Deserializer& source, const Vector3& position, const Quaternion& rotation, CreateMode mode = REPLICATED);
    /// Clear scene completely of nodes and components.
    void Clear();
    /// %Set active flag. Only active scenes will be updated automatically.
    void SetActive(bool enable);
    /// %Set network client motion smoothing constant.
    void SetSmoothingConstant(float constant);
    /// %Set network client motion smoothing snap threshold.
    void SetSnapThreshold(float threshold);
    /// Add a required package file for networking. To be called on the server.
    void AddRequiredPackageFile(PackageFile* package);
    /// Clear required package files.
    void ClearRequiredPackageFiles();
    /// Reset specific owner reference from nodes on disconnect.
    void ResetOwner(Connection* owner);
    /// Register a node user variable hash reverse mapping (for editing.)
    void RegisterVar(const String& name);
    /// Unregister a node user variable hash reverse mapping.
    void UnregisterVar(const String& name);
    /// Clear all registered node user variable hash reverse mappings.
    void UnregisterAllVars();
    
    /// Return node from the whole scene by ID, or null if not found.
    Node* GetNode(unsigned id) const;
    /// Return component from the whole scene by ID, or null if not found.
    Component* GetComponent(unsigned id) const;
    /// Return active flag.
    bool IsActive() const { return active_; }
    /// Return asynchronous loading flag.
    bool IsAsyncLoading() const { return asyncLoading_; }
    /// Return asynchronous loading progress between 0.0 and 1.0, or 1.0 if not in progress.
    float GetAsyncProgress() const;
    /// Return source file name.
    const String& GetFileName() const { return fileName_; }
    /// Return source file checksum.
    unsigned GetChecksum() const { return checksum_; }
    /// Return motion smoothing constant.
    float GetSmoothingConstant() const { return smoothingConstant_; }
    /// Return motion smoothing snap threshold.
    float GetSnapThreshold() const { return snapThreshold_; }
    /// Return required package files.
    const Vector<SharedPtr<PackageFile> >& GetRequiredPackageFiles() const { return requiredPackageFiles_; }
    /// Return all replicated scene nodes.
    const HashMap<unsigned, Node*>& GetReplicatedNodes() const { return replicatedNodes_; }
    /// Return a node user variable name, or empty if not registered.
    const String& GetVarName(ShortStringHash hash) const;
    
    /// Update scene. Called by HandleUpdate.
    void Update(float timeStep);
    /// Begin a threaded update. During threaded update components can choose to delay dirty processing.
    void BeginThreadedUpdate();
    /// End a threaded update. Notify components that marked themselves for delayed dirty processing.
    void EndThreadedUpdate();
    /// Add a component to the delayed dirty notify queue. Is thread-safe.
    void DelayedMarkedDirty(Component* component);
    /// Return threaded update flag.
    bool IsThreadedUpdate() const { return threadedUpdate_; }
    /// Get free node ID, either non-local or local.
    unsigned GetFreeNodeID(CreateMode mode);
    /// Get free component ID, either non-local or local.
    unsigned GetFreeComponentID(CreateMode mode);
    /// Node added. Assign scene pointer and add to ID map.
    void NodeAdded(Node* node);
    /// Node removed. Remove from ID map.
    void NodeRemoved(Node* node);
    /// Component added. Add to ID map.
    void ComponentAdded(Component* component);
    /// Component removed. Remove from ID map.
    void ComponentRemoved(Component* component);
    /// %Set node user variable reverse mappings.
    void SetVarNamesAttr(String value);
    /// Return node user variable reverse mappings.
    String GetVarNamesAttr() const;
    
private:
    /// Handle the logic update event to update the scene, if active.
    void HandleUpdate(StringHash eventType, VariantMap& eventData);
    /// Update asynchronous loading.
    void UpdateAsyncLoading();
    /// Finish asynchronous loading.
    void FinishAsyncLoading();
    /// Finish loading. Sets the scene filename and checksum.
    void FinishLoading(Deserializer* source);
    
    /// Replicated scene nodes by ID.
    HashMap<unsigned, Node*> replicatedNodes_;
    /// Local scene nodes by ID.
    HashMap<unsigned, Node*> localNodes_;
    /// Replicated components by ID.
    HashMap<unsigned, Component*> replicatedComponents_;
    /// Local components by ID.
    HashMap<unsigned, Component*> localComponents_;
    /// Asynchronous loading progress.
    AsyncProgress asyncProgress_;
    /// Node and component ID resolver for asynchronous loading.
    SceneResolver resolver_;
    /// Source file name.
    String fileName_;
    /// Required package files for networking.
    Vector<SharedPtr<PackageFile> > requiredPackageFiles_;
    /// Registered node user variable reverse mappings.
    HashMap<ShortStringHash, String> varNames_;
    /// Delayed dirty notification queue for components.
    PODVector<Component*> delayedDirtyComponents_;
    /// Mutex for the delayed dirty notification queue.
    Mutex sceneMutex_;
    /// Next free non-local node ID.
    unsigned replicatedNodeID_;
    /// Next free local node ID.
    unsigned localNodeID_;
    /// Next free non-local component ID.
    unsigned replicatedComponentID_;
    /// Next free local component ID.
    unsigned localComponentID_;
    /// Scene source file checksum.
    unsigned checksum_;
    /// Motion smoothing constant.
    float smoothingConstant_;
    /// Motion smoothing snap threshold.
    float snapThreshold_;
    /// Active flag.
    bool active_;
    /// Asynchronous loading flag.
    bool asyncLoading_;
    /// Threaded update flag.
    bool threadedUpdate_;
};

/// Register Scene library objects.
void RegisterSceneLibrary(Context* context);