Document ViewportTexture limitations and dynamic nature#121763
Open
Arecher wants to merge 2 commits into
Open
Conversation
- Added clearer explanation of `Viewport.get_texture()` returning a 'video view' rather than a static texture. - Improved explanation of what 'dynamic' represents in `ViewportTexture`'s description - Added note on ViewportTexture's limitation of being displayed within their own Viewport.
- Avoided using similar words too much - Switched sentence structure around to make it flow better - Added Oxford comma to part of the documentation that was lacking one.
viewport texture limitations and dynamic natureViewportTexture limitations and dynamic nature
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Viewport.get_texture()returning a 'video view' rather than a static texture.ViewportTexture's descriptionWhat problem(s) does this PR solve?
Additional information
I'm expecting this to be a first version of this documentation, since I'm not entirely familiar with the exact cause, symptoms or reasons behind the limitation, but I thought it should be documented in some way at least.
Open Questions
I would like to mention why the limitation to Viewports exists, so users have a better understanding of why this is not allowed and how to work around this if they need to. But I'm not entirely familiar with what the exact reason is. Is it that the child
ViewportTextureneeds theViewportto be rendered, but theViewportneeds toViewportTextureto be rendered first, causing a cyclic dependency? Is it that you cannot 'write' to the texture while it's being 'read'?. Similarly, apart from the errors I'm not sure what the consequences are. Does the ViewportTexture not display, or does the Viewport not work anymore, or are there no further consequences? I'm sure my current write-up is at least somewhat off, so I welcome any more accurate or useful descriptions of the limitation, why it occurs and what the results are.I added a note on the
ViewportTexturealways updating, and referred to theSubViewport.render_target_update_mode. This doesn't exist forViewportandWindowas far as I'm aware, but does represent the most familiar way to adjust how often aViewportupdates to most users, so referencing it felt useful. But I'm not sure if it's allowed to reference a subclass in the main classes documentation like this.Reason for change
The limitation discussed in the linked issue occurs frequently enough to warrant a note, especially with how simple of a mistake it is to make. The update to the
ViewportTexturedocumentation and explanation of it's 'dynamic' nature stems fromget_texture()not being the most descriptive method, and the documentation previously hinging completely on the word 'dynamic', which is too vague to instantly give users the correct expectations. The tutorial on viewports does a better job in that regard.