Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Transformações de janela de exibição e tela

Introdução

Esta é uma visão geral das transformações 2D que ocorrem para os nós desde o momento em que eles desenham seu conteúdo localmente até o momento em que são desenhados na tela. Esta visão geral discute detalhes de nível muito baixo do mecanismo.

The goal of this tutorial is to teach a way for feeding input events to the Input with a position in the correct coordinate system.

A more extensive description of all coordinate systems and 2d transforms is available in 2D coordinate systems and 2D transforms.

Transformação de tela

Como mencionado no tutorial anterior, Camadas de canvas, cada nó CanvasItem (lembre-se que os nós baseados em Node2D e Control usam CanvasItem como sua raiz comum) residirão em uma Canvas Layer. Cada camada de canvas tem uma transformação (translação, rotação, escala, etc.) que pode ser acessada como Transform2D.

Também abordado no tutorial anterior, os nós são desenhados por padrão na Camada 0, na tela embutida. Para colocar nós em uma camada diferente, um nó CanvasLayer pode ser usado.

Transformação global de canvas

Viewports also have a Global Canvas transform (also a Transform2D). This is the master transform and affects all individual Canvas Layer transforms. Generally, this is primarily used in Godot's CanvasItem Editor.

Transformação de alongamento

Finalmente, as viewports possuem uma Stretch Transform, que é usada ao redimensionar ou esticar a tela. Esta transformação é usada internamente (conforme descrito em Resoluções múltiplas), mas também pode ser configurada manualmente em cada viewport.

Input events are multiplied by this transform but lack the ones above. To convert InputEvent coordinates to local CanvasItem coordinates, the CanvasItem.make_input_local() function was added for convenience.

Window transform

The root viewport is a Window. In order to scale and position the Window's content as described in Resoluções múltiplas, each Window contains a window transform. It is for example responsible for the black bars at the Window's sides so that the Viewport is displayed with a fixed aspect ratio.

Ordem de transformação

To convert a CanvasItem local coordinate to an actual screen coordinate, the following chain of transforms must be applied:

../../_images/viewport_transforms3.webp

Funções de transformação

The above graphic shows some available transform functions. All transforms are directed from right to left, this means multiplying a transform with a coordinate results in a coordinate system further to the left, multiplying the affine inverse of a transform results in a coordinate system further to the right:

# Called from a CanvasItem.
canvas_pos = get_global_transform() * local_pos
local_pos = get_global_transform().affine_inverse() * canvas_pos

Finalmente, para converter as coordenadas locais de um CanvasItem em coordenadas de tela, basta multiplicar na seguinte ordem:

var screen_coord = get_viewport().get_screen_transform() * get_global_transform_with_canvas() * local_pos

Tenha em mente, no entanto, que geralmente não é desejável trabalhar com coordenadas de tela. A abordagem recomendada é simplesmente trabalhar nas coordenadas do Canvas (CanvasItem.get_global_transform()), para permitir que o redimensionamento automático da resolução da tela funcione corretamente.

Alimentando eventos de entrada personalizados

It is often desired to feed custom input events to the game. With the above knowledge, to correctly do this in the focused window, it must be done the following way:

var local_pos = Vector2(10, 20) # Local to Control/Node2D.
var ie = InputEventMouseButton.new()
ie.button_index = MOUSE_BUTTON_LEFT
ie.position = get_viewport().get_screen_transform() * get_global_transform_with_canvas() * local_pos
Input.parse_input_event(ie)