imguizmo (C++)

ImGuizmo: 3D gizmos to move, rotate and scale an object, a cube to orient the view, and small editors (curves, gradients, a sequencer).

ImGuizmo.h¶

Submodule im_guizmo¶

im_guizmo (struct)¶

im_guizmo::SetDrawlist¶

IMGUI_API void SetDrawlist(ImDrawList* drawlist = nullptr);

call inside your own window and before Manipulate() in order to draw gizmo to that window.
Or pass a specific ImDrawList to draw to (e.g. ImGui::GetForegroundDrawList()).

im_guizmo::BeginFrame¶

IMGUI_API void BeginFrame();

call BeginFrame right after ImGui_XXXX_NewFrame();

im_guizmo::SetImGuiContext¶

IMGUI_API void SetImGuiContext(ImGuiContext* ctx);

this is necessary because when imguizmo is compiled into a dll, and imgui into another globals are not shared between them.
More details at https://stackoverflow.com/questions/19373061/what-happens-to-global-and-static-variables-in-a-shared-library-when-it-is-dynam expose method to set imgui context

im_guizmo::IsOver¶

IMGUI_API bool IsOver();

IMGUI_API bool IsOver(OPERATION op);

return True if mouse cursor is over any gizmo control (axis, plan or screen component)

im_guizmo::IsUsing¶

IMGUI_API bool IsUsing();

return True if mouse IsOver or if the gizmo is in moving state

im_guizmo::IsUsingViewManipulate¶

IMGUI_API bool IsUsingViewManipulate();

return True if the view gizmo is in moving state

im_guizmo::IsViewManipulateHovered¶

IMGUI_API bool IsViewManipulateHovered();

only check if your mouse is over the view manipulator - no matter whether it’s active or not

im_guizmo::IsUsingAny¶

IMGUI_API bool IsUsingAny();

return True if any gizmo is in moving state

im_guizmo::Enable¶

IMGUI_API void Enable(bool enable);

enable/disable the gizmo. Stay in the state until next call to Enable. gizmo is rendered with gray half transparent color when disabled

im_guizmo::SetRect¶

IMGUI_API void SetRect(float x, float y, float width, float height);

helper functions for manualy editing translation/rotation/scale with an input float translation, rotation and scale float points to 3 floats each
Angles are in degrees (more suitable for human editing) example:

float matrixTranslation[3], matrixRotation[3], matrixScale[3];
ImGuizmo::DecomposeMatrixToComponents(gizmoMatrix.m16, matrixTranslation, matrixRotation, matrixScale);
ImGui::InputFloat3("Tr", matrixTranslation, 3);
ImGui::InputFloat3("Rt", matrixRotation, 3);
ImGui::InputFloat3("Sc", matrixScale, 3);
ImGuizmo::RecomposeMatrixFromComponents(matrixTranslation, matrixRotation, matrixScale, gizmoMatrix.m16);

These functions have some numerical stability issues for now. Use with caution.

im_guizmo::SetOrthographic¶

IMGUI_API void SetOrthographic(bool isOrthographic);

default is False

im_guizmo::OPERATION (enum)¶

enum OPERATION

call it when you want a gizmo
Needs view and projection matrices. matrix parameter is the source matrix (where will be gizmo be drawn) and might be transformed by the function. Return deltaMatrix is optional translation is applied in world space

im_guizmo::MODE (enum)¶

enum MODE

im_guizmo::SetAlternativeWindow¶

IMGUI_API void SetAlternativeWindow(ImGuiWindow* window);

im_guizmo::PushID¶

IMGUI_API void PushID(const char* str_id);

IMGUI_API void PushID(const void* ptr_id);

IMGUI_API void PushID(int int_id);

push string into the ID stack (will hash string).

im_guizmo::PopID¶

IMGUI_API void PopID();

pop from the ID stack.

im_guizmo::GetID¶

IMGUI_API ImGuiID GetID(const char* str_id);

IMGUI_API ImGuiID GetID(const void* ptr_id);

calculate unique ID (hash of whole ID stack + given parameter). e.g. if you want to query into ImGuiStorage yourself

im_guizmo::SetGizmoSizeClipSpace¶

IMGUI_API void SetGizmoSizeClipSpace(float value);

im_guizmo::MOVETYPE (enum)¶

enum MOVETYPE

Handle type used by the translate/rotate/scale gizmos.

im_guizmo::GetActiveHandleType¶

IMGUI_API MOVETYPE GetActiveHandleType();

Returns which handle is actively being dragged, or MT_NONE.

im_guizmo::GetHoveredHandleType¶

IMGUI_API MOVETYPE GetHoveredHandleType();

Returns which handle is currently hovered, or MT_NONE.

im_guizmo::GetActiveMoveType¶

IMGUI_API MOVETYPE GetActiveMoveType();

Aliases matching the MOVETYPE enum name.

im_guizmo::GetHoveredMoveType¶

IMGUI_API MOVETYPE GetHoveredMoveType();

im_guizmo::AllowAxisFlip¶

IMGUI_API void AllowAxisFlip(bool value);

Allow axis to flip
When True (default), the guizmo axis flip for better visibility
When False, they always stay along the positive world/local axis

im_guizmo::SetAxisLimit¶

IMGUI_API void SetAxisLimit(float value);

Configure the limit where axis are hidden

im_guizmo::SetAxisMask¶

IMGUI_API void SetAxisMask(bool x, bool y, bool z);

Set an axis mask to permanently hide a given axis (True -> hidden, False -> shown)

im_guizmo::SetPlaneLimit¶

IMGUI_API void SetPlaneLimit(float value);

Configure the limit where planes are hiden

im_guizmo::COLOR (enum)¶

enum COLOR

im_guizmo::Style (struct)¶

struct Style

im_guizmo::Style::Style¶

IMGUI_API Style();

im_guizmo::GetStyle¶

IMGUI_API Style& GetStyle();

}

im_guizmo::Matrix16 (struct)¶

struct Matrix16

im_guizmo::Matrix16::Matrix16¶

Matrix16();

explicit Matrix16(const std::array<float, 16>& v);

im_guizmo::Matrix6 (struct)¶

struct Matrix6

im_guizmo::Matrix6::Matrix6¶

Matrix6();

explicit Matrix6(const std::array<float, 6>& v);

im_guizmo::Matrix3 (struct)¶

struct Matrix3

im_guizmo::Matrix3::Matrix3¶

Matrix3();

explicit Matrix3(const std::array<float, 3>& v);

im_guizmo::MatrixComponents (struct)¶

struct MatrixComponents

im_guizmo::DecomposeMatrixToComponents¶

IMGUI_API MatrixComponents DecomposeMatrixToComponents(const Matrix16 &matrix);

helper functions for manualy editing translation/rotation/scale with an input float translation, rotation and scale float points to 3 floats each
Angles are in degrees (more suitable for human editing) example:

float matrixTranslation[3], matrixRotation[3], matrixScale[3];
ImGuizmo::DecomposeMatrixToComponents(gizmoMatrix.m16, matrixTranslation, matrixRotation, matrixScale);
ImGui::InputFloat3("Tr", matrixTranslation, 3);
ImGui::InputFloat3("Rt", matrixRotation, 3);
ImGui::InputFloat3("Sc", matrixScale, 3);
ImGuizmo::RecomposeMatrixFromComponents(matrixTranslation, matrixRotation, matrixScale, gizmoMatrix.m16);

These functions have some numerical stability issues for now. Use with caution.

im_guizmo::RecomposeMatrixFromComponents¶

IMGUI_API Matrix16 RecomposeMatrixFromComponents(const MatrixComponents& matrixComponents);

im_guizmo::DrawCubes¶

IMGUI_API void DrawCubes(const Matrix16& view, const Matrix16& projection, const std::vector<Matrix16> & matrices);

Render a cube with face color corresponding to face normal. Usefull for debug/tests

im_guizmo::DrawGrid¶

IMGUI_API void DrawGrid(const Matrix16& view, const Matrix16& projection, const Matrix16& matrix, const float gridSize);

im_guizmo::Manipulate¶

IMGUI_API bool Manipulate( const Matrix16& view, const Matrix16& projection, OPERATION operation, MODE mode, Matrix16& object_matrix, // This matrix may be modified! Matrix16* delta_matrix = nullptr, std::optional<Matrix3> snap = std::nullopt, std::optional<Matrix6> local_bounds = std::nullopt, std::optional<Matrix3> bounds_snap = std::nullopt );

Manipulate: main API of ImGuizmo
Returns True if the objectMatrix has been modified

Mandatory input parameters:

• view: camera view matrix (array of 16 floats)

• projection: camera projection matrix (array of 16 floats)

• operation: operation to perform (translate, rotate, scale)

• mode: in which space the operation is applied (local or world)
  Input / Output parameter:

• object_matrix: matrix of the object to manipulate (array of 16 floats) (will be modified when using the gizmo)

Optional output parameter:

• delta_matrix: matrix that contains the transformation delta (array of 16 floats) (useful to retrieve the modification between two frames) pass a newly created Matrix16, and it will be filled if not None.

Optional input parameters:

• snap: if not None, contains the snap value (array of 3 floats) (for example, if using TRANSLATE and snap={1,1,1}, the object will be snapped to the next integer position)

• local_bounds: if not None, contains the local bounds of the object (array of 6 floats)

• bounds_snap: if not None, contains the snap value for the bounds (array of 3 floats)

im_guizmo::ViewManipulate¶

IMGUI_API void ViewManipulate( Matrix16& view, // This matrix may be modified! float length, ImVec2 position, ImVec2 size, ImU32 backgroundColor);

IMGUI_API void ViewManipulate( Matrix16& view, const Matrix16& projection, OPERATION operation, MODE mode, Matrix16& matrix, // !!! float length, ImVec2 position, ImVec2 size, ImU32 backgroundColor); }

Please note that this cubeview is patented by Autodesk : https://patents.google.com/patent/US7782319B2/en
It seems to be a defensive patent in the US. I don’t think it will bring troubles using it as other software are using the same mechanics. But just in case, you are now warned!

ViewManipulate may change the view parameter