Caffeine

🔧 Transform Gizmos

Planned Milestone: M2 — Visual Editing & Assets Namespace: `Caffeine::Editor` Arquivos: `doppio-archived/src/doppio/editor/TransformGizmo.hpp`, `doppio-archived/src/doppio/editor/TransformGizmo.cpp` RF: RF6.1 Last updated:

Visão Geral#

Os Transform Gizmos são ferramentas visuais fundamentais para a manipulação direta de entidades no Viewport. Eles permitem que o utilizador altere a posição, rotação e escala de objetos sem a necessidade de introduzir valores numéricos manualmente no Inspector. Esta implementação foca-se numa experiência intuitiva, com suporte para snapping e modos de operação distintos.

O sistema suporta três modos principais: Translação (W), Rotação (E) e Escala (R). Cada modo fornece indicadores visuais claros sobre os eixos de manipulação, permitindo transformações precisas tanto em 2D como em 3D. A interação baseia-se em estados de hover e drag, garantindo que o utilizador saiba exatamente que eixo está a modificar antes de iniciar a ação.


Implementação#

O TransformGizmo atua como um sistema de overlay que interpreta as coordenadas do rato e as projeta no espaço do mundo ou da câmara para determinar colisões com os eixos do gizmo.

Diagramas de Interface#

text
Translate (W):       Rotate (E):          Scale (R):
     ▲ Y                  ◯                    ■ Y
     │                 ╱     ╲                 │
     └────► X          │       │               └────■ X
   ╱                 ╲       ╱               ╱
 ╱ Z (3D)              ╲   ╱               ╱ Z (3D)

Estrutura de Classes#

cpp
namespace Caffeine::Editor {

    enum class GizmoMode {
        None,
        Translate,
        Rotate,
        Scale
    };

    enum class GizmoAxis {
        None,
        X,
        Y,
        Z,
        Center
    };

    class TransformGizmo {
    public:
        TransformGizmo();
        ~TransformGizmo();

        void OnImGuiRender(Scene& scene, Entity selectedEntity);
        void SetMode(GizmoMode mode) { m_CurrentMode = mode; }
        
        // Atalhos de teclado
        void HandleInput();

    private:
        void RenderTranslate(const glm::vec3& position, const glm::quat& rotation);
        void RenderRotate(const glm::vec3& position, const glm::quat& rotation);
        void RenderScale(const glm::vec3& position, const glm::quat& rotation);

        bool IntersectAxis(GizmoAxis axis, const Ray& mouseRay);
        void ApplyTransform(Entity entity, const glm::vec3& delta);

        GizmoMode m_CurrentMode = GizmoMode::Translate;
        GizmoAxis m_ActiveAxis = GizmoAxis::None;
        
        float m_SnapValueTranslate = 16.0f; // px para 2D
        float m_SnapValueRotate = 45.0f;    // graus
        bool m_IsDragging = false;
    };
}

Lógica de Snapping#

Ao premir Shift durante a manipulação, os valores são arredondados para múltiplos configuráveis.

cpp
float ApplySnap(float value, float snapInterval) {
    if (snapInterval <= 0.0f) return value;
    return std::round(value / snapInterval) * snapInterval;
}

Decisões de Design#

Decisão Justificativa
Cores de Eixo (RGB) Padrão da indústria (X: Vermelho, Y: Verde, Z: Azul) para facilitar a aprendizagem.
Hover Highlight Mudar a cor do eixo para amarelo ao passar o rato evita manipulações acidentais do eixo errado.
Coordenadas de Ecrã Constantes O gizmo mantém o mesmo tamanho visual independentemente do zoom da câmara para garantir usabilidade.

Critério de Aceitação#

  • [ ] Pressionar W, E, R alterna entre os modos de translação, rotação e escala.
  • [ ] O eixo selecionado fica realçado em amarelo quando o cursor está por cima.
  • [ ] O arrasto de um eixo específico limita o movimento apenas a esse eixo.
  • [ ] O arrasto do centro permite movimento livre ou uniforme.
  • [ ] Manter Shift pressionado ativa o snapping (16px para posição, 45° para rotação).
  • [ ] O estado da entidade é atualizado em tempo real durante o arrasto.

Dependências#

  • Upstream: Caffeine::Core::Transform, Caffeine::Editor::Viewport
  • Downstream: Caffeine::Editor::SceneHierarchy

🔗 Tópicos Relacionados#

Tópico Descrição
Scene Editor Integração visual do gizmo com a renderização da cena.
Input System Captura de atalhos de teclado e eventos de rato.

Referências#

  • ImGuizmo Library (Architecture reference)
  • Unity/Unreal Engine Transform Tools