From 2b568faca04c421208fb7dd0b32d4b737f168aa8 Mon Sep 17 00:00:00 2001 From: Pavel Rojtberg Date: Thu, 8 Sep 2022 18:13:57 +0200 Subject: [PATCH] Docs: add DotScene to Manual --- .codedocs | 1 + Docs/CMakeLists.txt | 1 + Docs/src/tutorials/tutorials.md | 1 + PlugIns/DotScene/README.md | 39 +++++++++------------------------ 4 files changed, 13 insertions(+), 29 deletions(-) diff --git a/.codedocs b/.codedocs index 59e715eca29..8b902d7c3b5 100644 --- a/.codedocs +++ b/.codedocs @@ -682,6 +682,7 @@ INPUT = OgreMain/include \ Components/Volume/include \ PlugIns \ PlugIns/PCZSceneManager/docs/readme.md \ + PlugIns/DotScene/README.md \ RenderSystems \ Docs/src/apimainpage.md \ Docs/src/manual.md \ diff --git a/Docs/CMakeLists.txt b/Docs/CMakeLists.txt index 31b9bec641d..c8a91dc66cd 100644 --- a/Docs/CMakeLists.txt +++ b/Docs/CMakeLists.txt @@ -41,6 +41,7 @@ if(DOXYGEN_FOUND) ${COMPONENTS} ${PLUGINS} ${PROJECT_SOURCE_DIR}/PlugIns/PCZSceneManager/docs/readme.md + ${PROJECT_SOURCE_DIR}/PlugIns/DotScene/README.md ${PROJECT_SOURCE_DIR}/RenderSystems ${BASIC_TUTORIALS} ${PROJECT_SOURCE_DIR}/Docs/src/apimainpage.md diff --git a/Docs/src/tutorials/tutorials.md b/Docs/src/tutorials/tutorials.md index 2738725bfb9..22dff00e247 100644 --- a/Docs/src/tutorials/tutorials.md +++ b/Docs/src/tutorials/tutorials.md @@ -11,6 +11,7 @@ - @subpage trays - @subpage volume - @subpage meshlod-generator + - @subpage dotscene_overview - In Depth - @subpage manual-mesh-creation - @subpage tut_StaticGeom diff --git a/PlugIns/DotScene/README.md b/PlugIns/DotScene/README.md index a44554ef6c9..63046e21b99 100644 --- a/PlugIns/DotScene/README.md +++ b/PlugIns/DotScene/README.md @@ -1,4 +1,4 @@ -# DotScene Overview +# DotScene Overview {#dotscene_overview} DotScene (aka .scene) is just a standardized XML file format. @@ -6,13 +6,7 @@ This file format is meant to be used to set up a scene or scene-part. It is usef Besides Ogre, the [jMonkeyEngine](http://jmonkeyengine.org/) also supports loading .scene files. -## Index - - [What is DotScene?](#what-is-dotscene?) - - [User Data](#user-data) - - [How to use DotScene](#how-to-use-dotscene) - - [Instancing](#instancing) - - [Static Geometry](#static-geometry) - - [Instancie Manager](#instancie-manager) +@tableofcontents ## What is DotScene? DotScene file does not contain any mesh data, texture data, etc. It just contains elements that describe a scene. @@ -54,6 +48,7 @@ To add logic properties to the scene you can use the `` node as follow On the C++ side, these are acessible via e.g. ```cpp +Ogre::SceneManager* mSceneMgr = ...; mSceneMgr->getEntity("Cube")->getUserObjectBindings().getUserAny("mass"); ``` @@ -67,10 +62,10 @@ Plugin=Plugin_DotScene The Plugin will be then automatically used when you call `SceneNode::loadChildren()` like ```cpp -SceneNode* attachmentNode = mSceneMgr->getRootSceneNode()->createChildSceneNode(); +Ogre::SceneNode* attachmentNode = mSceneMgr->getRootSceneNode()->createChildSceneNode(); // Set the desired resource group first and then load the Scene -ResourceGroupManager::getSingleton().setWorldResourceGroupName("MyGroup"); +Ogre::ResourceGroupManager::getSingleton().setWorldResourceGroupName("MyGroup"); attachmentNode->loadChildren("myScene.scene"); ``` @@ -81,7 +76,10 @@ attachmentNode->getUserObjectBindings().getUserAny("TerrainGroup"); The type is `std::shared_ptr`, hence `attachmentNode` owns it and will take it down on destruction. ## Instancing -The DotScene Plugin can process the static / instanced attributes of the Entity definition to add them to the scene as either [Static Geometry](https://ogrecave.github.io/ogre/api/latest/class_ogre_1_1_static_geometry.html) or [Instanced meshes](https://ogrecave.github.io/ogre/api/latest/class_ogre_1_1_instance_manager.html). +The DotScene Plugin can process the static / instanced attributes of the Entity definition to add them to the scene as either Static Geometry or Instanced meshes. + +@see @ref WhatIsInstancing +@see @ref tut_StaticGeom ### Static Geometry If your scene has entities with the *static* property then the name referenced by the property is interpreted by the plugin as the name of the Static Geometry Group @@ -94,13 +92,9 @@ The plugin requires that the Static Geometry group or instance is created before Continuing with the example above, supose you created a scene with entities belonging to the "Foliage" group. ```cpp -SceneNode* attachmentNode = mSceneMgr->getRootSceneNode()->createChildSceneNode(); - // Create the StaticGeometry Ogre::StaticGeometry* sg = mSceneMgr->createStaticGeometry("Foliage"); -// Set the desired resource group first and then load the Scene -ResourceGroupManager::getSingleton().setWorldResourceGroupName("MyGroup"); attachmentNode->loadChildren("myScene.scene"); // Build the StaticGeometry after loading the Scene @@ -109,11 +103,6 @@ sg->build(); Any configuration for the StaticGeometry should be done before the `build()` call. -Please consult the documentation to know more about StaticGeometry and its use: - - [Ogre::StaticGeometry Class Reference](https://ogrecave.github.io/ogre/api/latest/class_ogre_1_1_static_geometry.html) - - [Tutorial - Static Geometry](https://ogrecave.github.io/ogre/api/latest/tut__static_geom.html) - - ### Instance Manager If your scene has entities with the *instanced* property then the name referenced by the property is interpreted by the plugin as the name of the Instance Manager For example: @@ -124,21 +113,13 @@ For example: The plugin requires that the Instance Manager is created before loading the Scene. Continuing with the example above, supose you created a scene with entities that you want to create with the "Foliage" Instance Manager. -> **NOTE:** Be aware that only the first submesh of the mesh is taken into account, if you have an Entity with many submeshes only the first one will be shown. +@note Be aware that only the first submesh of the mesh is taken into account, if you have an Entity with many submeshes only the first one will be shown. ```cpp -SceneNode* attachmentNode = mSceneMgr->getRootSceneNode()->createChildSceneNode(); - // Create the InstanceManager Ogre::InstanceManager* im = mSceneMgr->createInstanceManager("Foliage", "Cube.mesh", "MyGroup", Ogre::InstanceManager::ShaderBased, 80, Ogre::IM_USEALL); -// Set the desired resource group first and then load the Scene -ResourceGroupManager::getSingleton().setWorldResourceGroupName("MyGroup"); attachmentNode->loadChildren("myScene.scene"); ``` Any configuration for the InstanceManager should be done before calling `loadChildren()` - -Please consult the documentation to know more about Instancing and its use: - - [Ogre::InstanceManager Class Reference](https://ogrecave.github.io/ogre/api/latest/class_ogre_1_1_instance_manager.html) - - [What is instancing?](https://ogrecave.github.io/ogre/api/latest/instancing.html)