More work on Property documentation

2026-01-02 01:30:34 -06:00 · 2017-07-25 00:21:17 -04:00
parent e148cf28d0
commit 46c1fbb902
8 changed files with 168 additions and 58 deletions
--- a/modules/base/rendering/renderableplane.cpp
+++ b/modules/base/rendering/renderableplane.cpp
@@ -257,10 +257,10 @@ void RenderablePlane::render(const RenderData& data, RendererTasks&) {
        OsEng.renderEngine().rendererImplementation() == RenderEngine::RendererImplementation::ABuffer;

    if (usingABufferRenderer) {
-        _shader->setUniform("additiveBlending", _blendMode == BlendMode::Additive);
+        _shader->setUniform("additiveBlending", _blendMode == BlendModeAdditive);
    }

-    bool additiveBlending = _blendMode == BlendMode::Additive && usingFramebufferRenderer;
+    bool additiveBlending = _blendMode == BlendModeAdditive && usingFramebufferRenderer;
    if (additiveBlending) {
        glDepthMask(false);
        glBlendFunc(GL_SRC_ALPHA, GL_ONE);
--- a/modules/base/translation/statictranslation.cpp
+++ b/modules/base/translation/statictranslation.cpp
@@ -44,6 +44,12 @@ documentation::Documentation StaticTranslation::Documentation() {
        "Static Translation",
        "base_transform_translation_static",
        {
+            {
+                "Type",
+                new StringEqualVerifier("StaticTranslation"),
+                "",
+                Optional::No
+            },
            {
                PositionInfo.identifier,
                new DoubleVector3Verifier,
@@ -73,7 +79,7 @@ StaticTranslation::StaticTranslation(const ghoul::Dictionary& dictionary)
    documentation::testSpecificationAndThrow(
        Documentation(),
        dictionary,
-        "StaticEphemeris"
+        "StaticTranslation"
    );

    _position = dictionary.value<glm::dvec3>(PositionInfo.identifier);
--- a/modules/globebrowsing/rendering/layer/layer.cpp
+++ b/modules/globebrowsing/rendering/layer/layer.cpp
@@ -37,29 +37,55 @@ namespace {
    const char* keySettings = "Settings";
    const char* keyAdjustment = "Adjustment";
    const char* KeyBlendMode = "BlendMode";
+
+    static const openspace::properties::Property::PropertyInfo TypeInfo = {
+        "Type",
+        "Type",
+        "The type of this Layer. This value is a read-only property and thus cannot be "
+        "changed."
+    };
+
+    static const openspace::properties::Property::PropertyInfo BlendModeInfo = {
+        "BlendMode",
+        "Blend Mode",
+        "This value specifies the blend mode that is applied to this layer. The blend "
+        "mode determines how this layer is added to the underlying layers beneath."
+    };
+
+    static const openspace::properties::Property::PropertyInfo EnabledInfo = {
+        "Enabled",
+        "Enabled",
+        "If this value is enabled, the layer will be used for the final composition of "
+        "the planet. If this value is disabled, the layer will be ignored in the "
+        "composition."
+    };
+
+    static const openspace::properties::Property::PropertyInfo ResetInfo = {
+        "Reset",
+        "Reset",
+        "If this value is triggered, this layer will be reset. This will delete the "
+        "local cache for this layer and will trigger a fresh load of all tiles."
+    };
+
+    static const openspace::properties::Property::PropertyInfo ColorInfo = {
+        "Color",
+        "Color",
+        "If the 'Type' of this layer is a solid color, this value determines what this "
+        "solid color is."
+    };
+
 } // namespace

 Layer::Layer(layergroupid::GroupID id, const ghoul::Dictionary& layerDict)
    : properties::PropertyOwner(layerDict.value<std::string>(keyName))
-    , _typeOption(
-        { "Type", "Type", "" }, // @TODO Missing documentation
-        properties::OptionProperty::DisplayType::Dropdown
-    )
-    , _blendModeOption(
-        { "BlendMode", "Blend Mode", "" }, // @TODO Missing documentation
-        properties::OptionProperty::DisplayType::Dropdown
-    )
-    , _enabled({ "Enabled", "Enabled", "" }, false) // @TODO Missing documentation
-    , _reset({ "Reset", "Reset", "" }) // @TODO Missing documentation
+    , _typeOption(TypeInfo, properties::OptionProperty::DisplayType::Dropdown)
+    , _blendModeOption(BlendModeInfo, properties::OptionProperty::DisplayType::Dropdown)
+    , _enabled(EnabledInfo, false)
+    , _reset(ResetInfo)
    , _tileProvider(nullptr)
-    , _otherTypesProperties{
-        properties::Vec3Property (
-        { "Color", "Color", "" }, // @TODO Missing documentation
-        glm::vec4(1.f, 1.f, 1.f, 1.f),
-        glm::vec4(0.f),
-        glm::vec4(1.f)
-        )
-    }
+    , _otherTypesProperties({
+        { ColorInfo, glm::vec4(1.f), glm::vec4(0.f), glm::vec4(1.f) }
+    })
    , _layerGroupId(id)
 {
    layergroupid::TypeID typeID = parseTypeIdFromDictionary(layerDict);
--- a/modules/globebrowsing/rendering/layer/layeradjustment.cpp
+++ b/modules/globebrowsing/rendering/layer/layeradjustment.cpp
@@ -28,29 +28,34 @@ namespace {
    const char* keyType = "Type";
    const char* keyChromaKeyColor = "ChromaKeyColor";
    const char* keyChromaKeyTolerance = "ChromaKeyTolerance";
+
+    static const openspace::properties::Property::PropertyInfo ChromaKeyColorInfo = {
+        "ChromaKeyColor",
+        "Chroma Key Color",
+        "This color is used as the chroma key for the layer that is adjusted."
+    };
+
+    static const openspace::properties::Property::PropertyInfo ChromaKeyToleranceInfo = {
+        "ChromaKeyTolerance",
+        "Chroma Key Tolerance",
+        "This value determines the tolerance that is used to determine whether a color "
+        "is matching the selected Chroma key."
+    };
+
+    static const openspace::properties::Property::PropertyInfo TypeInfo = {
+        "Type",
+        "Type",
+        "The type of layer adjustment that is applied to the underlying layer."
+    };
 } // namespace

 namespace openspace::globebrowsing {

 LayerAdjustment::LayerAdjustment()
    : properties::PropertyOwner("adjustment")
-    , chromaKeyColor(
-        { "ChromaKeyColor", "Chroma key color", "" }, // @TODO Missing documentation
-        glm::vec3(0.f, 0.f, 0.f),
-        glm::vec3(0.f),
-        glm::vec3(1.f)
-      )
-    , chromaKeyTolerance(
-        { "ChromaKeyTolerance", "Chroma key tolerance", "" }, // @TODO Missing documentation
-        0,
-        0,
-        1
-      )
-    , _typeOption(
-        { "Type", "Type", "" }, // @TODO Missing documentation
-        properties::OptionProperty::DisplayType::Dropdown
-      )
-    , _onChangeCallback([](){})
+    , chromaKeyColor(ChromaKeyColorInfo, glm::vec3(0.f), glm::vec3(0.f), glm::vec3(1.f))
+    , chromaKeyTolerance(ChromaKeyToleranceInfo, 0.f, 0.f, 1.f)
+    , _typeOption(TypeInfo, properties::OptionProperty::DisplayType::Dropdown)
 {
    // Add options to option properties
    for (int i = 0; i < layergroupid::NUM_ADJUSTMENT_TYPES; ++i) {
@@ -63,7 +68,9 @@ LayerAdjustment::LayerAdjustment()
        removeVisibleProperties();
        _type = static_cast<layergroupid::AdjustmentTypeID>(_typeOption.value());
        addVisibleProperties();
-        _onChangeCallback();
+        if (_onChangeCallback) {
+            _onChangeCallback();
+        }
    });
    chromaKeyColor.setViewOption(properties::Property::ViewOptions::Color);

--- a/modules/globebrowsing/rendering/layer/layergroup.cpp
+++ b/modules/globebrowsing/rendering/layer/layergroup.cpp
@@ -28,14 +28,23 @@

 namespace {
    const char* _loggerCat = "LayerGroup";
-}
+
+    static const openspace::properties::Property::PropertyInfo BlendTileInfo = {
+        "BlendTileLevels",
+        "Blend between levels",
+        "If this value is enabled, images between different levels are interpolated, "
+        "rather than switching between levels abruptly. This makes transitions smoother "
+        "and more visually pleasing."
+    };
+
+} // namespace

 namespace openspace::globebrowsing {

 LayerGroup::LayerGroup(layergroupid::GroupID id)
    : properties::PropertyOwner(std::move(layergroupid::LAYER_GROUP_NAMES[id]))
    , _groupId(id)
-    , _levelBlendingEnabled({ "BlendTileLevels", "blend tile levels", "" }, false) // @TODO Missing documentation
+    , _levelBlendingEnabled(BlendTileInfo, true)
 {
    addProperty(_levelBlendingEnabled);
 }
--- a/modules/globebrowsing/rendering/layer/layerrendersettings.cpp
+++ b/modules/globebrowsing/rendering/layer/layerrendersettings.cpp
@@ -30,17 +30,52 @@ namespace {
    const char* keyMultiplier = "Multiplier";
    const char* keyOffset = "Offset";
    const char* keyValueBlending = "ValueBlending";
+
+    static const openspace::properties::Property::PropertyInfo SetDefaultInfo = {
+        "SetDefault",
+        "Set Default",
+        "If this value is triggered it will reset all of these values to their default "
+        "values."
+    };
+
+    static const openspace::properties::Property::PropertyInfo OpacityInfo = {
+        "Opacity",
+        "Opacity",
+        "This value sets the transparency of this layer. If this value is equal to '1', "
+        "the layer is completely opaque. If this value is equal to '0', the layer is "
+        "completely transparent."
+    };
+
+    static const openspace::properties::Property::PropertyInfo GammaInfo = {
+        "Gamma",
+        "Gamma",
+        "This value is used as an exponent to adjust the color for each tile."
+    };
+
+    static const openspace::properties::Property::PropertyInfo MultiplierInfo = {
+        "Multiplier",
+        "Multiplier",
+        "This value is used as a multiplier to adjust the color applied after taking the "
+        "gamma value as an exponent."
+    };
+
+    static const openspace::properties::Property::PropertyInfo OffsetInfo = {
+        "Offset",
+        "Offset",
+        "This value is used as an additive modifier to adjust the color applied after "
+        "the gamma exponent and the multiplier has been performed."
+    };
 } // namespace

 namespace openspace::globebrowsing {

 LayerRenderSettings::LayerRenderSettings()
    : properties::PropertyOwner("Settings")
-    , setDefault({ "SetDefault", "Set Default", "" }) // @TODO Missing documentation
-    , opacity(properties::FloatProperty({ "Opacity", "Opacity", "" }, 1.f, 0.f, 1.f)) // @TODO Missing documentation
-    , gamma(properties::FloatProperty({ "Gamma", "Gamma", "" }, 1, 0, 5))// @TODO Missing documentation
-    , multiplier(properties::FloatProperty({ "Multiplier", "Multiplier", "" }, 1.f, 0.f, 20.f))// @TODO Missing documentation
-    , offset(properties::FloatProperty({ "Offset", "Offset", "" }, 0.f, -10000.f, 10000.f))// @TODO Missing documentation
+    , setDefault(SetDefaultInfo)
+    , opacity(OpacityInfo, 1.f, 0.f, 1.f)
+    , gamma(GammaInfo, 1.f, 0.f, 5.f)
+    , multiplier(MultiplierInfo, 1.f, 0.f, 20.f)
+    , offset(OffsetInfo, 0.f, -10000.f, 10000.f)
    , valueBlending(properties::FloatProperty({ "ValueBlending", "Value Blending", "" }, // @TODO Missing documentation
                                               1.f, 0.f, 1.f))
    , useValueBlending(false)
--- a/modules/globebrowsing/tile/rawtiledatareader/gdalwrapper.cpp
+++ b/modules/globebrowsing/tile/rawtiledatareader/gdalwrapper.cpp
@@ -37,6 +37,20 @@

 namespace {
    const char* _loggerCat = "GdalWrapper";
+
+    static const openspace::properties::Property::PropertyInfo LogGdalErrorInfo = {
+        "LogGdalErrors",
+        "Log GDAL errors",
+        "If this value is enabled, any error that is raised by GDAL will be logged using "
+        "the logmanager. If this value is disabled, any error will be ignored."
+    };
+
+    static const openspace::properties::Property::PropertyInfo GdalMaximumCacheInfo = {
+        "GdalMaximumCacheSize",
+        "GDAL maximum cache size",
+        "This function sets the maximum amount of RAM memory in MB that GDAL is "
+        "permitted to use for caching."
+    };
 } // namespace

 namespace openspace::globebrowsing {
@@ -56,8 +70,7 @@ void gdalErrorHandler(CPLErr eErrClass, int errNo, const char *msg) {
 GdalWrapper* GdalWrapper::_singleton = nullptr;
 std::mutex GdalWrapper::_mutexLock;

-void GdalWrapper::create(size_t maximumCacheSize,
-                         size_t maximumMaximumCacheSize) {
+void GdalWrapper::create(size_t maximumCacheSize, size_t maximumMaximumCacheSize) {
    std::lock_guard<std::mutex> guard(_mutexLock);
    _singleton = new GdalWrapper(maximumCacheSize, maximumMaximumCacheSize);
 }
@@ -85,12 +98,11 @@ bool GdalWrapper::logGdalErrors() const {
    return _logGdalErrors;
 }

-GdalWrapper::GdalWrapper(size_t maximumCacheSize,
-                         size_t maximumMaximumCacheSize)
+GdalWrapper::GdalWrapper(size_t maximumCacheSize, size_t maximumMaximumCacheSize)
    : PropertyOwner("GdalWrapper")
-    , _logGdalErrors({ "LogGdalErrors", "Log GDAL errors", "" }, true) // @TODO Missing documentation
+    , _logGdalErrors(LogGdalErrorInfo, true)
    , _gdalMaximumCacheSize (
-        { "GdalMaximumCacheSize", "GDAL maximum cache size", "" }, // @TODO Missing documentation
+        GdalMaximumCacheInfo,
        maximumCacheSize / (1024 * 1024),           // Default
        0,                                          // Minimum: No caching
        maximumMaximumCacheSize / (1024 * 1024),    // Maximum
--- a/modules/globebrowsing/tile/tileprovider/defaulttileprovider.cpp
+++ b/modules/globebrowsing/tile/tileprovider/defaulttileprovider.cpp
@@ -49,14 +49,30 @@ namespace {
    const char* KeyFilePath = "FilePath";
    const char* KeyBasePath = "BasePath";
    const char* KeyPreCacheLevel = "PreCacheLevel";
+
+    static const openspace::properties::Property::PropertyInfo FilePathInfo = {
+        "FilePath",
+        "File Path",
+        "The path of the GDAL file or the image file that is to be used in this tile "
+        "provider."
+    };
+
+    static const openspace::properties::Property::PropertyInfo TilePixelSizeInfo = {
+        "TilePixelSize",
+        "Tile Pixel Size",
+        "This value is the preferred size (in pixels) for each tile. Choosing the right "
+        "value is a tradeoff between more efficiency (larger images) and better quality "
+        "(smaller images). The tile pixel size has to be smaller than the size of the "
+        "complete image if a single image is used."
+    };
 }

 namespace openspace::globebrowsing::tileprovider {
    
 DefaultTileProvider::DefaultTileProvider(const ghoul::Dictionary& dictionary) 
    : TileProvider(dictionary)
-    , _filePath({ "FilePath", "File Path", "" }, "") // @TODO Missing documentation
-    , _tilePixelSize({ "TilePixelSize", "Tile Pixel Size", "" }, 32, 32, 1024) // @TODO Missing documentation
+    , _filePath(FilePathInfo, "")
+    , _tilePixelSize(TilePixelSizeInfo, 32, 32, 2048)
    , _preCacheLevel(0)
 {
    _tileCache = OsEng.moduleEngine().module<GlobeBrowsingModule>()->tileCache();
@@ -105,11 +121,10 @@ DefaultTileProvider::DefaultTileProvider(const ghoul::Dictionary& dictionary)
    addProperty(_tilePixelSize);
 }

-DefaultTileProvider::DefaultTileProvider(
-    std::shared_ptr<AsyncTileDataProvider> tileReader)
+DefaultTileProvider::DefaultTileProvider(std::shared_ptr<AsyncTileDataProvider> tileReader)
    : _asyncTextureDataProvider(tileReader)
-    , _filePath({ "filePath", "File Path", "" }, "") // @TODO Missing documentation
-    , _tilePixelSize({ "tilePixelSize", "Tile Pixel Size", "" }, 32, 32, 1024) // @TODO Missing documentation
+    , _filePath(FilePathInfo, "")
+    , _tilePixelSize(TilePixelSizeInfo, 32, 32, 2048)
 {}

 DefaultTileProvider::~DefaultTileProvider() {}