Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update description of shader variable TIME and add description to Fog, Particle, Sky, and Spatial shader pages #9734

Merged
merged 1 commit into from
Aug 14, 2024

Conversation

tetrapod00
Copy link
Contributor

@tetrapod00 tetrapod00 commented Aug 11, 2024

Added/changed description of TIME in CanvasItem, Fog, Particle, Sky, and Spatial shader pages. Description now links to other relevant docs pages. Added a label to the global uniform header of shading_languge.rst, so it can be cross referenced from elsewhere.

I made some changes in addition to simply copying the existing description from CanvasItem shaders to the other pages. Should close #9725.

I wrote for a user who is new-ish to shaders, notices that TIME does not exactly match CPU time behavior, and finds any of the shader pages. Ideally they can come away the exact behavior of the built-in TIME uniform, as well as a way to make their own if need be. I based this on my interactions with users in various discords who asked about TIME.

New description which appears on each shader page:

Global time since the engine has started, in seconds. It repeats after every 3,600 seconds (which can be changed with the rollover setting). It's not affected by time_scale or pausing. If you need a TIME variable that can be scaled or paused, add your own global shader uniform and update it each frame.

Old description, from the CanvasItem shader page:

Global time since the engine has started, in seconds (always positive). It's subject to the rollover setting (which is 3,600 seconds by default). It's not affected by time_scale or pausing, but you can define a global shader uniform to add a "scaled" TIME variable if desired.

Changes:

  • Now links to the rollover setting in project settings. This is important, because searching for "rollover" in the docs does not actually surface the setting in ProjectSettings, only this page.
  • Now links to the global shader uniform documentation. A label is added to the global uniform header in that docs page. I may have gotten the preferred syntax wrong for this.
  • Uses more active language for the sentence about adding your own TIME uniform.
  • Clarifies that the value repeats rather than merely "being subject to" the rollover setting.
  • Emphasizes the default value of 3,600 seconds first, because a user finding this page is unlikely to have changed that value.
  • No longer mentions that the value is "always positive". If this is necessary, I would suggest "always in the range of 0 to 3,600" or "always in the range of 0 to rollover".

If any of these changes break docs style, or are otherwise too much, I can revert to more minimal changes.

Also sent in godotengine/godot#95381, so that the link to the setting from the shader docs page doesn't point to an empty description.

…header

Added/changed description of TIME in CanvasItem, Fog, Particle, Sky, and Spatial shader pages. Description now links to other relevant docs pages. Added a label to the global uniform header of shading_languge.rst, so it can be cross referenced from elsewhere.
@skyace65 skyace65 added enhancement area:manual Issues and PRs related to the Manual/Tutorials section of the documentation topic:shaders labels Aug 11, 2024
@tetrapod00 tetrapod00 changed the title Add description of TIME to shaders, add label to global uniform header Update description of shader variable TIME and add description to Fog, Particle, Sky, and Spatial shader pages Aug 11, 2024
Copy link
Member

@clayjohn clayjohn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great to me! Good work

@clayjohn clayjohn added this to the 4.3 milestone Aug 14, 2024
@skyace65 skyace65 merged commit 603f4dc into godotengine:master Aug 14, 2024
1 check passed
@skyace65
Copy link
Contributor

Thanks!

@tetrapod00 tetrapod00 deleted the time-shader branch August 14, 2024 23:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation enhancement topic:shaders
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add a complete description of TIME to Spatial, Particle, Sky, and Fog shaders.
3 participants