跳至主要內容

RenderingServer.viewport_create

EVOCOSMOS2026/4/14大约 6 分钟

最后同步日期：2026-04-15 | Godot 官方原文 — RenderingServer.viewport_create

RenderingServer.viewport_create

定义

RenderingServer.viewport_create() 是底层渲染服务器提供的方法，用于创建一个新的视口（Viewport）资源，并返回一个视口 RID。

视口可以理解为"一块虚拟的画布"——引擎把 3D 场景和 2D 内容渲染到这块画布上，然后再把画布的内容显示到屏幕上，或者作为纹理贴到其他物体表面。比如游戏中的小地图、监控摄像头画面、后视镜等，都是不同视口的渲染结果。

普通开发中我们用的是 SubViewport 节点，而 RenderingServer.viewport_create() 则绕过节点系统，直接在渲染服务器层面创建视口，适合需要精细控制渲染管线的场景。

函数签名

C#
public static Rid ViewportCreate()

参数说明

参数类型必需说明
———此函数不接受任何参数

返回值

类型： Rid（资源 ID）

返回新创建的视口的 RID。后续所有对该视口的操作（设置大小、挂载场景、绑定摄像机等）都需要用到这个 RID。

代码示例

基础用法：创建视口并设置基本属性

C#
using Godot;

public partial class BasicViewportDemo : Node
{
    private Rid _viewportRid;

    public override void _Ready()
    {
        // 1. 创建视口
        _viewportRid = RenderingServer.ViewportCreate();

        // 2. 设置视口大小（512x512 像素）
        RenderingServer.ViewportSetSize(_viewportRid, 512, 512);

        // 3. 启用更新（默认是禁用的）
        RenderingServer.ViewportSetActive(_viewportRid, true);

        // 4. 设置渲染场景为当前场景
        var sceneRid = GetTree().Root.GetViewportRid();
        // 注意：这里仅为演示，实际需要通过 scenario 关联
        var scenarioRid = RenderingServer.ViewportGetScenario(
            GetViewport().GetViewportRid()
        );
        RenderingServer.ViewportSetScenario(_viewportRid, scenarioRid);

        GD.Print("视口创建完成，RID: ", _viewportRid);
        GD.Print("视口大小: 512x512");
        // 运行结果: 视口创建完成，RID: RID(0, 2)
        // 运行结果: 视口大小: 512x512
    }

    public override void _ExitTree()
    {
        RenderingServer.FreeRid(_viewportRid);
    }
}

实际场景：创建渲染纹理用于监控画面

C#
using Godot;

/// <summary>
/// 创建一个独立的视口，把它的渲染结果作为纹理
/// 显示在 UI 上的 TextureRect 中，模拟监控摄像头效果。
/// </summary>
public partial class SurveillanceCamera : Node3D
{
    private Rid _cameraRid;
    private Rid _viewportRid;

    [Export] public TextureRect DisplayRect { get; set; }
    [Export] public int ExViewportWidth = 256;
    [Export] public int ExViewportHeight = 256;

    public override void _Ready()
    {
        // 1. 创建视口
        _viewportRid = RenderingServer.ViewportCreate();
        RenderingServer.ViewportSetSize(_viewportRid, ExViewportWidth, ExViewportHeight);
        RenderingServer.ViewportSetActive(_viewportRid, true);

        // 关联到当前场景的渲染环境
        var scenarioRid = RenderingServer.ViewportGetScenario(
            GetViewport().GetViewportRid()
        );
        RenderingServer.ViewportSetScenario(_viewportRid, scenarioRid);

        // 设置视口更新模式为每帧更新
        RenderingServer.ViewportSetUpdateMode(
            _viewportRid,
            RenderingServer.ViewportUpdateMode.Always
        );

        // 设置视口输出为纹理
        RenderingServer.ViewportSetRenderTargetVFlip(_viewportRid, true);

        // 2. 创建摄像机并挂载到视口
        _cameraRid = RenderingServer.CameraCreate();
        RenderingServer.CameraSetPerspective(_cameraRid, fov: 60f, znear: 0.05f, zfar: 100f);

        var camTransform = GlobalTransform;
        RenderingServer.CameraSetTransform(_cameraRid, camTransform);
        RenderingServer.ViewportAttachCamera(_viewportRid, _cameraRid);

        // 3. 将视口纹理显示到 UI 上
        if (DisplayRect != null)
        {
            var viewportTexture = RenderingServer.ViewportGetTexture(_viewportRid);
            DisplayRect.Texture = viewportTexture;
            GD.Print("监控画面已连接到显示区域");
        }
        // 运行结果: 监控画面已连接到显示区域
    }

    public override void _ExitTree()
    {
        RenderingServer.FreeRid(_cameraRid);
        RenderingServer.FreeRid(_viewportRid);
    }
}

进阶用法：分屏多人游戏视口

C#
using Godot;

/// <summary>
/// 分屏多人游戏示例：为每个玩家创建独立的视口和摄像机，
/// 实现上下分屏效果（适合双人本地对战）。
/// </summary>
public partial class SplitScreenManager : Node
{
    private Rid _viewport1;
    private Rid _viewport2;
    private Rid _camera1;
    private Rid _camera2;

    [Export] public Node3D Player1 { get; set; }
    [Export] public Node3D Player2 { get; set; }

    public override void _Ready()
    {
        var mainViewportRid = GetViewport().GetViewportRid();
        var screenWidth = (int)GetViewport().GetVisibleRect().Size.X;
        var screenHeight = (int)GetViewport().GetVisibleRect().Size.Y;
        var halfHeight = screenHeight / 2;

        // 获取场景环境
        var scenarioRid = RenderingServer.ViewportGetScenario(mainViewportRid);

        // ---- 玩家 1 的视口（上半屏）----
        _viewport1 = RenderingServer.ViewportCreate();
        RenderingServer.ViewportSetSize(_viewport1, screenWidth, halfHeight);
        RenderingServer.ViewportSetActive(_viewport1, true);
        RenderingServer.ViewportSetScenario(_viewport1, scenarioRid);
        RenderingServer.ViewportSetUpdateMode(
            _viewport1, RenderingServer.ViewportUpdateMode.Always
        );

        _camera1 = RenderingServer.CameraCreate();
        RenderingServer.CameraSetPerspective(_camera1, fov: 65f, znear: 0.1f, zfar: 200f);
        RenderingServer.ViewportAttachCamera(_viewport1, _camera1);

        // ---- 玩家 2 的视口（下半屏）----
        _viewport2 = RenderingServer.ViewportCreate();
        RenderingServer.ViewportSetSize(_viewport2, screenWidth, halfHeight);
        RenderingServer.ViewportSetActive(_viewport2, true);
        RenderingServer.ViewportSetScenario(_viewport2, scenarioRid);
        RenderingServer.ViewportSetUpdateMode(
            _viewport2, RenderingServer.ViewportUpdateMode.Always
        );

        _camera2 = RenderingServer.CameraCreate();
        RenderingServer.CameraSetPerspective(_camera2, fov: 65f, znear: 0.1f, zfar: 200f);
        RenderingServer.ViewportAttachCamera(_viewport2, _camera2);

        GD.Print($"分屏设置完成: {screenWidth}x{halfHeight} x 2");
        // 运行结果: 分屏设置完成: 1920x540 x 2
    }

    public override void _Process(double delta)
    {
        // 每帧更新摄像机位置跟随各自玩家
        if (Player1 != null)
        {
            var t1 = Player1.GlobalTransform;
            var offset1 = new Transform3D(Basis.Identity, t1.Origin + new Vector3(0, 5, 8));
            offset1 = offset1.LookingAt(t1.Origin, Vector3.Up);
            RenderingServer.CameraSetTransform(_camera1, offset1);
        }

        if (Player2 != null)
        {
            var t2 = Player2.GlobalTransform;
            var offset2 = new Transform3D(Basis.Identity, t2.Origin + new Vector3(0, 5, 8));
            offset2 = offset2.LookingAt(t2.Origin, Vector3.Up);
            RenderingServer.CameraSetTransform(_camera2, offset2);
        }
    }

    public override void _ExitTree()
    {
        RenderingServer.FreeRid(_camera1);
        RenderingServer.FreeRid(_camera2);
        RenderingServer.FreeRid(_viewport1);
        RenderingServer.FreeRid(_viewport2);
    }
}

注意事项

  1. 必须手动释放资源：通过 RenderingServer.viewport_create() 创建的视口不会随节点树自动销毁，务必在 _ExitTree() 中调用 RenderingServer.FreeRid() 释放。

  2. 新视口默认不活跃：创建后需要调用 ViewportSetActive(viewportRid, true) 才能启用渲染。

  3. 必须设置大小：新创建的视口大小默认为 0x0，必须通过 ViewportSetSize() 设置具体的像素尺寸。

  4. 需要关联场景环境：视口需要通过 ViewportSetScenario() 关联到某个渲染场景（scenario），否则无法看到任何 3D 内容。

  5. 优先使用 SubViewport 节点：绝大多数情况下使用场景树中的 SubViewport 节点就足够了，更简单且不易出错。底层 API 适合需要同时管理大量视口、或需要极致性能优化的场景。

  6. 视口纹理获取：可以通过 RenderingServer.ViewportGetTexture(viewportRid) 获取视口的渲染结果纹理，用于贴图到 UI 或 3D 物体表面。

最近更新:
贡献者: zefeng.peng,bobokaka
EVOCOSMOS
Copyright © 2026 EVOCOSMOS