Skip to content

Commit

Permalink
improve doxygen formatting in some Hlms classes
Browse files Browse the repository at this point in the history
  • Loading branch information
@jwwalker @darksylinc
jwwalker authored and darksylinc committed Jul 31, 2024
1 parent a7a8764 commit c366477
Show file tree
Hide file tree
Showing 4 changed files with 45 additions and 21 deletions.
2 changes: 1 addition & 1 deletion Components/Hlms/Pbs/include/OgreHlmsPbsDatablock.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
35 changes: 23 additions & 12 deletions OgreMain/include/OgreHlms.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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.
Expand All @@ -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; }
Expand Down Expand Up @@ -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.
Expand All @@ -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
*/
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -812,15 +816,18 @@ 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 );
/// if( filename && resourceGroup && !filename->empty() && !resourceGroup->empty() )
/// {
/// //Valid filename & resource group.
/// }
/// @endcode
void getFilenameAndResourceGroup( IdString name, String const **outFilename,
String const **outResourceGroup ) const;

Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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 );

Expand All @@ -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
Expand All @@ -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;
Expand Down
27 changes: 19 additions & 8 deletions OgreMain/include/OgreHlmsDatablock.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
Expand All @@ -504,6 +510,8 @@ namespace Ogre
datablock->setBlendblock( &blendblock );
datablock->setAlphaHashing( true );
@endcode
@endparblock
@param bAlphaHashing
True to enable alpha hashing.
*/
Expand Down Expand Up @@ -548,14 +556,17 @@ 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 );
/// if( filename && resourceGroup && !filename->empty() && !resourceGroup->empty() )
/// {
/// //Valid filename & resource group.
/// }
/// @endcode
void getFilenameAndResourceGroup( String const **outFilename,
String const **outResourceGroup ) const;

Expand Down
2 changes: 2 additions & 0 deletions OgreMain/include/OgreHlmsListener.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit c366477

Please sign in to comment.