Skip to content

Document ViewportTexture limitations and dynamic nature#121763

Open
Arecher wants to merge 2 commits into
godotengine:masterfrom
Arecher:Document-`ViewportTexture`-limitations-and-dynamic-nature
Open

Document ViewportTexture limitations and dynamic nature#121763
Arecher wants to merge 2 commits into
godotengine:masterfrom
Arecher:Document-`ViewportTexture`-limitations-and-dynamic-nature

Conversation

@Arecher

@Arecher Arecher commented Jul 25, 2026

Copy link
Copy Markdown
  • 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.

What 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 ViewportTexture needs the Viewport to be rendered, but the Viewport needs to ViewportTexture to 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 ViewportTexture always updating, and referred to the SubViewport.render_target_update_mode. This doesn't exist for Viewport and Window as far as I'm aware, but does represent the most familiar way to adjust how often a Viewport updates 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 ViewportTexture documentation and explanation of it's 'dynamic' nature stems from get_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.

Arecher added 2 commits July 25, 2026 12:06
- 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.
@Arecher
Arecher requested a review from a team as a code owner July 25, 2026 10:38
@Arecher Arecher changed the title Document viewport texture limitations and dynamic nature Document ViewportTexture limitations and dynamic nature Jul 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant