🔧 Transform Gizmos
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#
Translate (W): Rotate (E): Scale (R):
▲ Y ◯ ■ Y
│ ╱ ╲ │
└────► X │ │ └────■ X
╱ ╲ ╱ ╱
╱ Z (3D) ╲ ╱ ╱ Z (3D)
Estrutura de Classes#
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.
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