From c3664772b884b57f613890e697b6359002fe362c Mon Sep 17 00:00:00 2001 From: James Walker Date: Tue, 30 Jul 2024 15:56:46 -0700 Subject: [PATCH] improve doxygen formatting in some Hlms classes --- .../Hlms/Pbs/include/OgreHlmsPbsDatablock.h | 2 +- OgreMain/include/OgreHlms.h | 35 ++++++++++++------- OgreMain/include/OgreHlmsDatablock.h | 27 +++++++++----- OgreMain/include/OgreHlmsListener.h | 2 ++ 4 files changed, 45 insertions(+), 21 deletions(-) diff --git a/Components/Hlms/Pbs/include/OgreHlmsPbsDatablock.h b/Components/Hlms/Pbs/include/OgreHlmsPbsDatablock.h index c93b21cc575..c8c2759e715 100644 --- a/Components/Hlms/Pbs/include/OgreHlmsPbsDatablock.h +++ b/Components/Hlms/Pbs/include/OgreHlmsPbsDatablock.h @@ -608,7 +608,7 @@ namespace Ogre @param transparency Value in range [0; 1] where 0 = full transparency and 1 = fully opaque. @param mode - @see TransparencyModes + see #TransparencyModes @param useAlphaFromTextures When false, the alpha channel of the diffuse maps and detail maps will be ignored. It's a GPU performance optimization. diff --git a/OgreMain/include/OgreHlms.h b/OgreMain/include/OgreHlms.h index 0dfc5dd4a57..c377d952345 100644 --- a/OgreMain/include/OgreHlms.h +++ b/OgreMain/include/OgreHlms.h @@ -90,11 +90,11 @@ namespace Ogre enum PrecisionMode { - /// midf datatype maps to float (i.e. 32-bit) + /// midf datatype maps to float (i.e., 32-bit) /// This setting is always supported PrecisionFull32, - /// midf datatype maps to float16_t (i.e. forced 16-bit) + /// midf datatype maps to float16_t (i.e., forced 16-bit) /// /// It forces the driver to produce 16-bit code, even if unoptimal /// Great for testing quality downgrades caused by 16-bit support @@ -596,7 +596,7 @@ namespace Ogre /// Call as early as possible. void setPrecisionMode( PrecisionMode precisionMode ); - /// Returns requested precision mode (i.e. value passed to setPrecisionMode) + /// Returns requested precision mode (i.e., value passed to setPrecisionMode) /// See getSupportedPrecisionMode PrecisionMode getPrecisionMode() const; @@ -625,6 +625,7 @@ namespace Ogre @see setAreaLightForwardSettings @param maxLights + @parblock Maximum number of non-caster directional lights. 0 to allow unlimited number of lights, at the cost of shader recompilations when directional lights are added or removed. @@ -636,6 +637,7 @@ namespace Ogre Beware of setting this value too high (e.g. 65535) as the amount of memory space is limited (we cannot exceed 64kb, including unrelated data to lighting, but required to the pass) + @endparblock */ void setMaxNonCasterDirectionalLights( uint16 maxLights ); uint16 getMaxNonCasterDirectionalLights() const { return mNumLightsLimit; } @@ -684,6 +686,7 @@ namespace Ogre /** Area lights use regular Forward. @param areaLightsApproxLimit + @parblock Maximum number of area approx lights that will be considered by the shader. Default value is 1. Use 0 to disable area lights. @@ -694,6 +697,7 @@ namespace Ogre Beware of setting this value too high (e.g. 65535) as the amount of memory space is limited (we cannot exceed 64kb, including unrelated data to lighting, but required to the pass) + @endparblock @param areaLightsLtcLimit Same as areaLightsApproxLimit, but for LTC lights */ @@ -770,9 +774,9 @@ namespace Ogre useful for UI editors which want to enumerate all existing datablocks and display its name to the user. @param macroblockRef - @see HlmsManager::getMacroblock + see HlmsManager::getMacroblock @param blendblockRef - @see HlmsManager::getBlendblock + see HlmsManager::getBlendblock @param paramVec Key - String Value list of paramters. MUST BE SORTED. @param visibleToManager @@ -812,8 +816,10 @@ namespace Ogre /// contain an empty string. /// The reason this String doesn't live in HlmsDatablock is to prevent /// cache trashing (datablocks are hot iterated every frame, and the - /// filename & resource groups are rarely ever used) + /// filename & resource groups are rarely ever used). + /// @par /// Usage: + /// @code /// String const *filename; /// String const *resourceGroup; /// datablock->getFilenameAndResourceGroup( &filename, &resourceGroup ); @@ -821,6 +827,7 @@ namespace Ogre /// { /// //Valid filename & resource group. /// } + /// @endcode void getFilenameAndResourceGroup( IdString name, String const **outFilename, String const **outResourceGroup ) const; @@ -856,11 +863,9 @@ namespace Ogre public: /** Called by the renderable when either it changes the material, - or its properties change (e.g. the mesh' uvs are stripped) + or its properties change (e.g., the mesh's uvs are stripped) @param renderable The renderable the material will be used on. - @param movableObject - The MovableObject the material will be used on (usually the parent of renderable) @param outHash A hash. This hash references property parameters that are already cached. */ @@ -1052,8 +1057,8 @@ namespace Ogre /** See HlmsDatablock::setCustomPieceCodeFromMemory & HlmsDatablock::setCustomPieceFile. @param filename Name of the file. - @param shaderCode - The contents of the file. + @param resourceGroup + The name of the resource group in which to look for the file. */ void _addDatablockCustomPieceFile( const String &filename, const String &resourceGroup ); @@ -1072,7 +1077,7 @@ namespace Ogre See _addDatablockCustomPieceFile() overload. Unlike the other overload, file not found errors are ignored. @param resourceGroup - See _addDatablockCustomPieceFile() overload. + The name of the resource group in which to look for the file. @param templateHash The expected hash of the file. File won't be added if the hash does not match. @return @@ -1082,6 +1087,12 @@ namespace Ogre const String &resourceGroup, const uint64 sourceCodeHash[2] ); + /** + @param filename + Name of the file. + @param sourceCode + The contents of the file. + */ void _addDatablockCustomPieceFileFromMemory( const String &filename, const String &sourceCode ); bool isDatablockCustomPieceFileCacheable( int32 filenameHashId ) const; diff --git a/OgreMain/include/OgreHlmsDatablock.h b/OgreMain/include/OgreHlmsDatablock.h index cf5ed685fcd..825ee34a7d0 100644 --- a/OgreMain/include/OgreHlmsDatablock.h +++ b/OgreMain/include/OgreHlmsDatablock.h @@ -188,11 +188,15 @@ namespace Ogre /// stencil buffer). uint8 mBlendChannelMask; - /// This value calculated by HlmsManager::getBlendblock - /// mIsTransparent = 0 -> Not transparent - /// mIsTransparent |= 1 -> Automatically determined as transparent - /// mIsTransparent |= 2 -> Forced to be considered as transparent by RenderQueue for render order - /// mIsTransparent = 3 -> Forced & also automatically determined as transparent + /// @parblock + /// This value calculated by HlmsManager::getBlendblock. + /// + /// - mIsTransparent = 0 -> Not transparent + /// - mIsTransparent |= 1 -> Automatically determined as transparent + /// - mIsTransparent |= 2 -> Forced to be considered as transparent by RenderQueue for render + /// order + /// - mIsTransparent = 3 -> Forced & also automatically determined as transparent + /// @endparblock uint8 mIsTransparent; /// Used to determine if separate alpha blending should be used for color and alpha channels bool mSeparateBlend; @@ -221,7 +225,7 @@ namespace Ogre void calculateSeparateBlendMode(); /** Sometimes you want to force the RenderQueue to render back to front even if - the object isn't alpha blended (e.g. you're rendering refractive materials) + the object isn't alpha blended (e.g., you're rendering refractive materials) @param bForceTransparent True to always render back to front, like any transparent. False for default behavior (opaque objects are rendered front to back, alpha @@ -424,7 +428,7 @@ namespace Ogre Runs an O(N) search to get the right block. Calling this function triggers a HlmsDatablock::flushRenderables @param macroblock - @see HlmsManager::getMacroblock + see HlmsManager::getMacroblock @param casterBlock True to directly set the macroblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant. @@ -454,7 +458,7 @@ namespace Ogre Runs an O(N) search to get the right block. Calling this function triggers a HlmsDatablock::flushRenderables @param blendblock - @see HlmsManager::getBlendblock + see HlmsManager::getBlendblock @param casterBlock True to directly set the blendblock to be used during the shadow mapping's caster pass. When false, the value of overrideCasterBlock becomes relevant. @@ -494,8 +498,10 @@ namespace Ogre Calling this function triggers a HlmsDatablock::flushRenderables @remarks + @parblock For best results: + @code // Disable alpha test (default) datablock->setAlphaTest( CMPF_ALWAYS_PASS ); // Do NOT enable alpha blending in the HlmsBlendblock (default) @@ -504,6 +510,8 @@ namespace Ogre datablock->setBlendblock( &blendblock ); datablock->setAlphaHashing( true ); + @endcode + @endparblock @param bAlphaHashing True to enable alpha hashing. */ @@ -548,7 +556,9 @@ namespace Ogre /// @see Hlms::getFilenameAndResourceGroup. This operation is NOT fast. Might return /// null (if the datablock was removed from the Hlms but somehow is still alive) + /// @par /// Usage: + /// @code /// String const *filename; /// String const *resourceGroup; /// datablock->getFilenameAndResourceGroup( &filename, &resourceGroup ); @@ -556,6 +566,7 @@ namespace Ogre /// { /// //Valid filename & resource group. /// } + /// @endcode void getFilenameAndResourceGroup( String const **outFilename, String const **outResourceGroup ) const; diff --git a/OgreMain/include/OgreHlmsListener.h b/OgreMain/include/OgreHlmsListener.h index 6b374debc6c..1ee52b29b4a 100644 --- a/OgreMain/include/OgreHlmsListener.h +++ b/OgreMain/include/OgreHlmsListener.h @@ -63,12 +63,14 @@ namespace Ogre generated yet) and the properties are before they are transformed by the templates @brief propertiesMergedPreGenerationStep @param hlms + @parblock Pointer to caller. WARNING: Note that any modified property WON'T BE CACHED. If you set a property based on external information, it will break caches. You can only set new properties that are derived from existing properties e.g. c = a + b, which means caching a and b will always result in c being the same value + @endparblock @param passCache Properties used by this pass @param renderableCacheProperties