Transformación de Viewport y Canvas

Introducción

This is an overview of the 2D transforms going on for nodes from the moment they draw their content locally to the time they are drawn onto the screen. This overview discusses very low-level details of the engine.

El objetivo de este tutorial es enseñar una manera de enviar eventos de entrada al Input con una posición en el sistema de coordenadas correcto.

Una descripción más extensa de todos los sistemas de coordenadas y transformaciones 2D está disponible en 2D coordinate systems and 2D transforms.

Transformación del canvas

Como se mencionó en el tutorial anterior, Capas de Canvas, cada nodo CanvasItem (recuerda que los nodos basados en Node2D y Control usan CanvasItem como su raíz común) residirá en una Canvas Layer. Cada canvas layer tiene una transformación (translation, rotation, scale, etc.) a la que se puede acceder mediante Transform2D.

Esto también está cubierto por el tutorial anterior, los nodos son dibujados por defecto en Layer (capa) 0, en el "built-in canvas" (el canvas por defecto del viewport). Para colocar nodos en una capa distinta, se debe utilizar una CanvasLayer.

Transformación global del canvas

Los Viewports también tienen una transformación Global Canvas (también un Transform2D). Esta es la transformación principal y afecta a todas las transformaciones individuales de Canvas Layer. Generalmente esta transformación es usada en el Editor de CanvasItem de Godot.

Transformación de estiramiento

Por último, los Viewports tienen un Stretch Transform, que se utiliza al cambiar de tamaño o estirar la pantalla. Esta transformación se utiliza internamente (como se describe en Múltiples resoluciones) pero también se puede configurar manualmente en 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.

Transform de Window

El viewport raíz es una :ref: Window. Para poder escalar y posicionar el contenido de Window's como se describe en Múltiples resoluciones, cada Window contiene un window transform. Este es, por ejemplo, responsabe por las barras negras a los costados de Window's así el Viewport se muestra con una relación de aspecto fija.

Orden de Transform

Para convertir un sistema de coordenadas locales de CanvasItem en coordenadas de pantalla, se debe aplicar la siguiente secuencia de transforms:

Funciones de Transform

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:

GDScriptC#

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

Finalmente, para convertir un CanvasItem de coordenadas locales a coordenadas de pantalla, utilizar el siguiente orden:

GDScriptC#

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

Tener en cuenta que esto no es aconsejable para trabajar en coordenadas de pantalla. Lo recomendable es simplemente trabajar en coordenadas de Canvas (CanvasItem.get_global_transform()), para permitir que el cambio de tamaño/ajuste de resolución funcione de la manera adecuada.

Generando eventos de entrada personalizados

Usualmente es deseable crear eventos de entradas personalizados para el juego. Con lo aprendido anteriormente, para hacerlo de manera correcta en la ventana enfocada, se debe hacer lo siguiente:

GDScriptC#

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)