Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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

Introdução

Esta é uma visão geral das transformações 2D que ocorrem nos nós desde o momento em que desenham seu conteúdo localmente até o momento em que são exibidos na tela. Esta visão geral aborda detalhes de nível muito baixo do motor.

O objetivo deste tutorial é ensinar uma maneira de alimentar eventos de entrada com uma posição no sistema de coordenadas correto.

Uma descrição mais extensa de todos os sistemas de coordenadas e transformações 2D está disponível em Sistemas de coordenadas 2D e transformações 2D.

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

Os Viewports também possuem uma transformação Global Canvas (também uma Transform2D). Esta é a transformação principal e afeta todas as transformações individuais de Canvas Layer. Em geral, isso é usado principalmente no Editor de CanvasItem do Godot.

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.

Os eventos de entrada (input) são multiplicados por essa transformação, mas carecem das mencionadas acima. Para converter coordenadas de InputEvent em coordenadas locais de CanvasItem, a função CanvasItem.make_input_local() foi adicionada por conveniência.

Transformação da janela

A viewport raiz é um node do tipo Window. Para dimensionar e posicionar o conteúdo da Window conforme descrito em Resoluções múltiplas, cada Window contém uma transformação da janela (window transform). Ela é responsável, por exemplo, pelas barras pretas nas laterais da Window para que a Viewport seja exibida com uma proporção fixa.

Ordem de transformação

Para converter uma coordenada local de um CanvasItem em uma coordenada real de tela, a seguinte cadeia de transformações deve ser aplicada:

Funções de transformação

A imagem acima mostra algumas funções de transformação disponíveis. Todas as transformações são aplicadas da direita para a esquerda, o que significa que multiplicar uma transformação por uma coordenada resulta em um sistema de coordenadas mais à esquerda, enquanto multiplicar o inverso afim de uma transformação resulta em um sistema de coordenadas mais à direita:

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

// Called from a CanvasItem.
canvasPos = GetGlobalTransform() * localPos;
localPos = GetGlobalTransform().AffineInverse() * canvasPos;

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

var screenCoord = GetViewport().GetScreenTransform() * GetGlobalTransformWithCanvas() * localPos;

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

Frequentemente é desejável fornecer eventos de entrada personalizados ao jogo. Com o conhecimento acima, para fazer isso corretamente na janela em foco, deve-se proceder da seguinte forma:

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)

var localPos = new Vector2(10,20); // Local to Control/Node2D.
var ie = new InputEventMouseButton()
{
    ButtonIndex = MouseButton.Left,
    Position = GetViewport().GetScreenTransform() * GetGlobalTransformWithCanvas() * localPos,
};
Input.ParseInputEvent(ie);