Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

SubViewport

Inherits: Viewport < Node < Object

Creates a sub-view into the screen.

Description

SubViewport is a Viewport that isn't a Window, i.e. it doesn't draw anything by itself. To display something, SubViewport's size must be non-zero and it should be either put inside a SubViewportContainer or assigned to a ViewportTexture.

Tutorials

• Using Viewports

• Viewport and canvas transforms

• GUI in 3D Demo

• 3D in 2D Demo

• 2D in 3D Demo

• Screen Capture Demo

• Dynamic Split Screen Demo

• 3D Viewport Scaling Demo

Properties

ClearMode	render_target_clear_mode	0
UpdateMode	render_target_update_mode	2
Vector2i	size	Vector2i(512, 512)
Vector2i	size_2d_override	Vector2i(0, 0)
bool	size_2d_override_stretch	false

---

Enumerations

enum ClearMode:

ClearMode CLEAR_MODE_ALWAYS = 0

Always clear the render target before drawing.

ClearMode CLEAR_MODE_NEVER = 1

Never clear the render target.

ClearMode CLEAR_MODE_ONCE = 2

Clear the render target on the next frame, then switch to CLEAR_MODE_NEVER.

---

enum UpdateMode:

UpdateMode UPDATE_DISABLED = 0

Do not update the render target.

UpdateMode UPDATE_ONCE = 1

Update the render target once, then switch to UPDATE_DISABLED.

UpdateMode UPDATE_WHEN_VISIBLE = 2

Update the render target only when it is visible. This is the default value.

UpdateMode UPDATE_WHEN_PARENT_VISIBLE = 3

Update the render target only when its parent is visible.

UpdateMode UPDATE_ALWAYS = 4

Always update the render target.

---

Property Descriptions

ClearMode render_target_clear_mode = 0

• void set_clear_mode ( ClearMode value )

• ClearMode get_clear_mode ( )

The clear mode when the sub-viewport is used as a render target.

Note: This property is intended for 2D usage.

---

UpdateMode render_target_update_mode = 2

• void set_update_mode ( UpdateMode value )

• UpdateMode get_update_mode ( )

The update mode when the sub-viewport is used as a render target.

---

Vector2i size = Vector2i(512, 512)

• void set_size ( Vector2i value )

• Vector2i get_size ( )

The width and height of the sub-viewport. Must be set to a value greater than or equal to 2 pixels on both dimensions. Otherwise, nothing will be displayed.

Note: If the parent node is a SubViewportContainer and its SubViewportContainer.stretch is true, the viewport size cannot be changed manually.

---

Vector2i size_2d_override = Vector2i(0, 0)

• void set_size_2d_override ( Vector2i value )

• Vector2i get_size_2d_override ( )

The 2D size override of the sub-viewport. If either the width or height is 0, the override is disabled.

---

bool size_2d_override_stretch = false

• void set_size_2d_override_stretch ( bool value )

• bool is_size_2d_override_stretch_enabled ( )

If true, the 2D size override affects stretch as well.