From 1778a7cdb6190c231b07181cb6631b7815ee863c Mon Sep 17 00:00:00 2001 From: Alexander Bock Date: Thu, 15 Sep 2016 13:28:52 +0200 Subject: [PATCH] Add documentation to SceneGraphNode --- include/openspace/scene/scenegraphnode.h | 4 + src/CMakeLists.txt | 1 + src/scene/scene_doc.inl | 5 +- src/scene/scenegraphnode.cpp | 19 ++- src/scene/scenegraphnode_doc.inl | 145 +++++++++++++++++++++++ 5 files changed, 170 insertions(+), 4 deletions(-) create mode 100644 src/scene/scenegraphnode_doc.inl diff --git a/include/openspace/scene/scenegraphnode.h b/include/openspace/scene/scenegraphnode.h index 4979eedcf8..1a08eeb54a 100644 --- a/include/openspace/scene/scenegraphnode.h +++ b/include/openspace/scene/scenegraphnode.h @@ -26,6 +26,8 @@ #define __SCENEGRAPHNODE_H__ // open space includes +#include + #include #include #include @@ -106,6 +108,8 @@ public: _ephemeris = eph; } + static Documentation Documentation(); + private: bool sphereInsideFrustum(const psc& s_pos, const PowerScaledScalar& s_rad, const Camera* camera); diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index c81f3999cc..6c87e7cd57 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -85,6 +85,7 @@ set(OPENSPACE_SOURCE ${OPENSPACE_BASE_DIR}/src/scene/scene_lua.inl ${OPENSPACE_BASE_DIR}/src/scene/scenegraph.cpp ${OPENSPACE_BASE_DIR}/src/scene/scenegraphnode.cpp + ${OPENSPACE_BASE_DIR}/src/scene/scenegraphnode_doc.inl ${OPENSPACE_BASE_DIR}/src/scripting/lualibrary.cpp ${OPENSPACE_BASE_DIR}/src/scripting/scriptengine.cpp ${OPENSPACE_BASE_DIR}/src/scripting/scriptengine_lua.inl diff --git a/src/scene/scene_doc.inl b/src/scene/scene_doc.inl index abd9c145e8..9b069572c1 100644 --- a/src/scene/scene_doc.inl +++ b/src/scene/scene_doc.inl @@ -29,7 +29,7 @@ namespace openspace { Documentation Scene::Documentation() { using namespace documentation; - return{ + return { "Scene Description", { { @@ -85,7 +85,8 @@ Documentation Scene::Documentation() { }), "This is the list of modules that will be loaded into the initial scene. The " "values in this table have to correspond to folders relative to the " - "ScenePath key." + "ScenePath key. The order in which the modules are loaded is the same as the " + "order in which they are specified in this table." } } }; diff --git a/src/scene/scenegraphnode.cpp b/src/scene/scenegraphnode.cpp index 3ac738de27..bf00e499ad 100644 --- a/src/scene/scenegraphnode.cpp +++ b/src/scene/scenegraphnode.cpp @@ -24,6 +24,9 @@ // open space includes #include + +#include + #include #include #include @@ -46,6 +49,8 @@ #include #include +#include "scenegraphnode_doc.inl" + namespace { const std::string _loggerCat = "SceneGraphNode"; const std::string KeyRenderable = "Renderable"; @@ -63,8 +68,18 @@ const std::string SceneGraphNode::KeyName = "Name"; const std::string SceneGraphNode::KeyParentName = "Parent"; const std::string SceneGraphNode::KeyDependencies = "Dependencies"; -SceneGraphNode* SceneGraphNode::createFromDictionary(const ghoul::Dictionary& dictionary) -{ +SceneGraphNode* SceneGraphNode::createFromDictionary(const ghoul::Dictionary& dictionary){ + // Perform testing against the documentation/specification + using namespace openspace::documentation; + TestResult testResult = testSpecification( + SceneGraphNode::Documentation(), + dictionary + ); + if (!testResult.success) { + throw SpecificationError(testResult, "SceneGraphNode"); + } + + SceneGraphNode* result = new SceneGraphNode; if (!dictionary.hasValue(KeyName)) { diff --git a/src/scene/scenegraphnode_doc.inl b/src/scene/scenegraphnode_doc.inl new file mode 100644 index 0000000000..b10c8e6468 --- /dev/null +++ b/src/scene/scenegraphnode_doc.inl @@ -0,0 +1,145 @@ +/***************************************************************************************** + * * + * OpenSpace * + * * + * Copyright (c) 2014-2016 * + * * + * 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. * + ****************************************************************************************/ + +#include + +namespace openspace { + +Documentation SceneGraphNode::Documentation() { + using namespace documentation; + + return { + "Scenegraph Node", + { + { + "Name", + new StringVerifier, + "The name of this scenegraph node. This name must be unique among all scene " + "graph nodes that are loaded in a specific scene. If a duplicate is detected " + "the loading of the node will fail, as will all childing that depend on the " + "node." + }, + { + "Parent", + new StringAnnotationVerifier( + "Must be a name for another scenegraph node, or 'Root'" + ), + "This names the parent of the currently specified scenegraph node. The " + "parent must not have been defined earlier, but must exist at loading time, " + "or the scenegraph node creation will fail. A special parent 'Root' is " + "available that denotes the root of the scenegraph." + }, + { + "Renderable", + new TableVerifier({ + { + "Type", + new StringAnnotationVerifier( + "Must name a valid Renderable type." + ), + "The type of the specific renderable. The list of available " + "renderables depends on the configuration of the application and can " + "be written to disk at startup." + } + }), + "The renderable that is to be created for this scenegraph node. A renderable " + "is a component of a scenegraph node that will lead to some visual result on " + "the screen. The specifics heavily depend on the 'Type' of the renderable. " + "If no Renderable is specified, this scenegraph node is an internal node and " + "can be used for either group children, or apply common transformations to a " + "group of children.", + Optional::Yes + }, + { + "Transform", + new TableVerifier({ + { + "Translation", + new TableVerifier({ + { + "Type", + new StringAnnotationVerifier( + "Must name a valid Translation type." + ), + "The type of translation that is described in this element. " + "The available types of translations depend on the " + "configuration of the application and can be written to disk " + "on application startup." + } + }), + "This node describes a translation that is applied to the scenegraph " + "node and all its children. Depending on the 'Type' of the " + "translation, this can either be a static translation or a " + "time-varying one.", + Optional::Yes + }, + { + "Rotation", + new TableVerifier({ + { + "Type", + new StringAnnotationVerifier( + "Must name a valid Rotation type." + ), + "The type of the rotation that is described in this element. " + "The available types of rotations depend on the " + "configuration of the application and can be written to disk " + "on application startup." + } + }), + "This nodes describes a rotation that is applied to the scenegraph " + "node and all its children. Depending on the 'Type' of the rotation, " + "this can either be a static rotation or a time-varying one.", + Optional::Yes + }, + { + "Scale", + new TableVerifier({ + { + "Type", + new StringAnnotationVerifier( + "Must name a valid Scale type." + ), + "The type of the scaling that is described in this element. " + "The available types of scaling depend on the configuration " + "of the application and can be written to disk on " + "application startup." + } + }), + "This node describes a scaling that is applied to the scenegraph " + "node and all its children. Depending on the 'Type' of the scaling, " + "this can either be a static scaling or a time-varying one.", + Optional::Yes + } + }), + "This describes a set of transformations that are applied to this scenegraph " + "node and all of its children. There are only three possible values " + "corresponding to a 'Translation', a 'Rotation', and a 'Scale'.", + Optional::Yes + }, + } + }; +} + +} // namespace openspace