GHOST_C-api.h

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once
 
#include "GHOST_Types.h"
 
#ifdef __cplusplus
extern "C" {
#endif

using GHOST_EventCallbackProcPtr = bool (*)(GHOST_EventHandle event, GHOST_TUserDataPtr user_data);

extern GHOST_SystemHandle GHOST_CreateSystem(void);
extern GHOST_SystemHandle GHOST_CreateSystemBackground(void);

extern void GHOST_SystemInitDebug(GHOST_SystemHandle systemhandle, GHOST_Debug debug);
 
#if !(defined(WIN32) || defined(__APPLE__))
extern const char *GHOST_SystemBackend(void);
#endif

extern GHOST_TSuccess GHOST_DisposeSystem(GHOST_SystemHandle systemhandle);

extern void GHOST_ShowMessageBox(GHOST_SystemHandle systemhandle,
                                 const char *title,
                                 const char *message,
                                 const char *help_label,
                                 const char *continue_label,
                                 const char *link,
                                 GHOST_DialogOptions dialog_options);

extern GHOST_EventConsumerHandle GHOST_CreateEventConsumer(
    GHOST_EventCallbackProcPtr eventCallback, GHOST_TUserDataPtr user_data);

extern GHOST_TSuccess GHOST_DisposeEventConsumer(GHOST_EventConsumerHandle consumerhandle);

extern uint64_t GHOST_GetMilliSeconds(GHOST_SystemHandle systemhandle);

extern GHOST_TimerTaskHandle GHOST_InstallTimer(GHOST_SystemHandle systemhandle,
                                                uint64_t delay,
                                                uint64_t interval,
                                                GHOST_TimerProcPtr timer_proc,
                                                GHOST_TUserDataPtr user_data);

extern GHOST_TSuccess GHOST_RemoveTimer(GHOST_SystemHandle systemhandle,
                                        GHOST_TimerTaskHandle timertaskhandle);
 
/***************************************************************************************
 * Display/window management functionality
 ***************************************************************************************/

extern uint8_t GHOST_GetNumDisplays(GHOST_SystemHandle systemhandle);

extern GHOST_TSuccess GHOST_GetMainDisplayDimensions(GHOST_SystemHandle systemhandle,
                                                     uint32_t *r_width,
                                                     uint32_t *r_height);

extern GHOST_TSuccess GHOST_GetAllDisplayDimensions(GHOST_SystemHandle systemhandle,
                                                    uint32_t *r_width,
                                                    uint32_t *r_height);
extern GHOST_WindowHandle GHOST_CreateWindow(GHOST_SystemHandle systemhandle,
                                             GHOST_WindowHandle parent_windowhandle,
                                             const char *title,
                                             int32_t left,
                                             int32_t top,
                                             uint32_t width,
                                             uint32_t height,
                                             GHOST_TWindowState state,
                                             bool is_dialog,
                                             GHOST_GPUSettings gpu_settings);

extern GHOST_ContextHandle GHOST_CreateGPUContext(GHOST_SystemHandle systemhandle,
                                                  GHOST_GPUSettings gpu_settings);

extern GHOST_TSuccess GHOST_DisposeGPUContext(GHOST_SystemHandle systemhandle,
                                              GHOST_ContextHandle contexthandle);

extern GHOST_TUserDataPtr GHOST_GetWindowUserData(GHOST_WindowHandle windowhandle);

extern void GHOST_SetWindowUserData(GHOST_WindowHandle windowhandle, GHOST_TUserDataPtr user_data);
 
extern bool GHOST_IsDialogWindow(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_DisposeWindow(GHOST_SystemHandle systemhandle,
                                          GHOST_WindowHandle windowhandle);

extern bool GHOST_ValidWindow(GHOST_SystemHandle systemhandle, GHOST_WindowHandle windowhandle);
 
/*
 **
 * Returns high dynamic range color information about this window.
 * \return HDR info.
 */
extern GHOST_WindowHDRInfo GHOST_WindowGetHDRInfo(GHOST_WindowHandle windowhandle);

extern GHOST_WindowHandle GHOST_GetWindowUnderCursor(GHOST_SystemHandle systemhandle,
                                                     int32_t x,
                                                     int32_t y);
 
/***************************************************************************************
 * Event management functionality
 ***************************************************************************************/

extern bool GHOST_ProcessEvents(GHOST_SystemHandle systemhandle, bool waitForEvent);

extern void GHOST_DispatchEvents(GHOST_SystemHandle systemhandle);

extern GHOST_TSuccess GHOST_AddEventConsumer(GHOST_SystemHandle systemhandle,
                                             GHOST_EventConsumerHandle consumerhandle);

extern GHOST_TSuccess GHOST_RemoveEventConsumer(GHOST_SystemHandle systemhandle,
                                                GHOST_EventConsumerHandle consumerhandle);
 
/***************************************************************************************
 * Progress bar functionality
 ***************************************************************************************/

extern GHOST_TSuccess GHOST_SetProgressBar(GHOST_WindowHandle windowhandle, float progress);

extern GHOST_TSuccess GHOST_EndProgressBar(GHOST_WindowHandle windowhandle);
 
/***************************************************************************************
 * Cursor management functionality
 ***************************************************************************************/

extern GHOST_TStandardCursor GHOST_GetCursorShape(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetCursorShape(GHOST_WindowHandle windowhandle,
                                           GHOST_TStandardCursor cursorshape);

extern GHOST_TSuccess GHOST_HasCursorShape(GHOST_WindowHandle windowhandle,
                                           GHOST_TStandardCursor cursorshape);

extern GHOST_TSuccess GHOST_SetCustomCursorShape(GHOST_WindowHandle windowhandle,
                                                 const uint8_t *bitmap,
                                                 const uint8_t *mask,
                                                 const int size[2],
                                                 const int hot_spot[2],
                                                 bool can_invert_color);
extern GHOST_TSuccess GHOST_SetCustomCursorGenerator(GHOST_WindowHandle windowhandle,
                                                     GHOST_CursorGenerator *cursor_generator);
 
extern GHOST_TSuccess GHOST_GetCursorBitmap(GHOST_WindowHandle windowhandle,
                                            GHOST_CursorBitmapRef *bitmap);

extern uint32_t GHOST_GetCursorPreferredLogicalSize(const GHOST_SystemHandle systemhandle);

extern bool GHOST_GetCursorVisibility(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetCursorVisibility(GHOST_WindowHandle windowhandle, bool visible);

GHOST_TSuccess GHOST_GetCursorPosition(const GHOST_SystemHandle systemhandle,
                                       const GHOST_WindowHandle windowhandle,
                                       int32_t *x,
                                       int32_t *y);
GHOST_TSuccess GHOST_SetCursorPosition(GHOST_SystemHandle systemhandle,
                                       GHOST_WindowHandle windowhandle,
                                       int32_t x,
                                       int32_t y);
 
void GHOST_GetCursorGrabState(GHOST_WindowHandle windowhandle,
                              GHOST_TGrabCursorMode *r_mode,
                              GHOST_TAxisFlag *r_axis_flag,
                              int r_bounds[4],
                              bool *r_use_software_cursor);

extern GHOST_TSuccess GHOST_SetCursorGrab(GHOST_WindowHandle windowhandle,
                                          GHOST_TGrabCursorMode mode,
                                          GHOST_TAxisFlag wrap_axis,
                                          const int bounds[4],
                                          const int mouse_ungrab_xy[2]);
 
/***************************************************************************************
 * Access to mouse button and keyboard states.
 ***************************************************************************************/

extern GHOST_TSuccess GHOST_GetModifierKeyState(GHOST_SystemHandle systemhandle,
                                                GHOST_TModifierKey mask,
                                                bool *r_is_down);

extern GHOST_TSuccess GHOST_GetButtonState(GHOST_SystemHandle systemhandle,
                                           GHOST_TButton mask,
                                           bool *r_is_down);
 
#ifdef WITH_INPUT_NDOF
/***************************************************************************************
 * Access to 3D mouse.
 ***************************************************************************************/

extern void GHOST_setNDOFDeadZone(float deadzone);
#endif
 
/***************************************************************************************
 * Drag & drop operations
 ***************************************************************************************/

extern void GHOST_setAcceptDragOperation(GHOST_WindowHandle windowhandle, bool can_accept);

extern GHOST_TEventType GHOST_GetEventType(GHOST_EventHandle eventhandle);

extern uint64_t GHOST_GetEventTime(GHOST_EventHandle eventhandle);

extern GHOST_WindowHandle GHOST_GetEventWindow(GHOST_EventHandle eventhandle);

extern GHOST_TEventDataPtr GHOST_GetEventData(GHOST_EventHandle eventhandle);

extern GHOST_TimerProcPtr GHOST_GetTimerProc(GHOST_TimerTaskHandle timertaskhandle);

extern void GHOST_SetTimerProc(GHOST_TimerTaskHandle timertaskhandle,
                               GHOST_TimerProcPtr timer_proc);

extern GHOST_TUserDataPtr GHOST_GetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle);

extern void GHOST_SetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle,
                                       GHOST_TUserDataPtr user_data);

extern bool GHOST_GetValid(GHOST_WindowHandle windowhandle);

extern GHOST_TDrawingContextType GHOST_GetDrawingContextType(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetDrawingContextType(GHOST_WindowHandle windowhandle,
                                                  GHOST_TDrawingContextType type);

extern GHOST_ContextHandle GHOST_GetDrawingContext(GHOST_WindowHandle windowhandle);

extern void GHOST_SetTitle(GHOST_WindowHandle windowhandle, const char *title);

extern char *GHOST_GetTitle(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetPath(GHOST_WindowHandle windowhandle, const char *filepath);

extern GHOST_TWindowDecorationStyleFlags GHOST_GetWindowDecorationStyleFlags(
    GHOST_WindowHandle windowhandle);

extern void GHOST_SetWindowDecorationStyleFlags(GHOST_WindowHandle windowhandle,
                                                GHOST_TWindowDecorationStyleFlags style_flags);

extern void GHOST_SetWindowDecorationStyleSettings(
    GHOST_WindowHandle windowhandle, GHOST_WindowDecorationStyleSettings decoration_settings);

extern GHOST_TSuccess GHOST_ApplyWindowDecorationStyle(GHOST_WindowHandle windowhandle);

extern GHOST_RectangleHandle GHOST_GetWindowBounds(GHOST_WindowHandle windowhandle);

extern GHOST_RectangleHandle GHOST_GetClientBounds(GHOST_WindowHandle windowhandle);

void GHOST_DisposeRectangle(GHOST_RectangleHandle rectanglehandle);

extern GHOST_TSuccess GHOST_SetClientWidth(GHOST_WindowHandle windowhandle, uint32_t width);

extern GHOST_TSuccess GHOST_SetClientHeight(GHOST_WindowHandle windowhandle, uint32_t height);

extern GHOST_TSuccess GHOST_SetClientSize(GHOST_WindowHandle windowhandle,
                                          uint32_t width,
                                          uint32_t height);

extern void GHOST_ScreenToClient(
    GHOST_WindowHandle windowhandle, int32_t inX, int32_t inY, int32_t *outX, int32_t *outY);

extern void GHOST_ClientToScreen(
    GHOST_WindowHandle windowhandle, int32_t inX, int32_t inY, int32_t *outX, int32_t *outY);

extern GHOST_TWindowState GHOST_GetWindowState(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetWindowState(GHOST_WindowHandle windowhandle,
                                           GHOST_TWindowState state);

extern GHOST_TSuccess GHOST_SetWindowModifiedState(GHOST_WindowHandle windowhandle,
                                                   bool is_unsaved_changes);

extern GHOST_TSuccess GHOST_SetWindowOrder(GHOST_WindowHandle windowhandle,
                                           GHOST_TWindowOrder order);

extern GHOST_TSuccess GHOST_SwapWindowBufferAcquire(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SwapWindowBufferRelease(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_SetSwapInterval(GHOST_WindowHandle windowhandle, int interval);

extern GHOST_TSuccess GHOST_GetSwapInterval(GHOST_WindowHandle windowhandle, int *r_interval);

extern GHOST_TSuccess GHOST_ActivateWindowDrawingContext(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_InvalidateWindow(GHOST_WindowHandle windowhandle);

extern GHOST_TSuccess GHOST_ActivateGPUContext(GHOST_ContextHandle contexthandle);

extern GHOST_TSuccess GHOST_ReleaseGPUContext(GHOST_ContextHandle contexthandle);

extern GHOST_ContextHandle GHOST_GetActiveGPUContext();

extern unsigned int GHOST_GetContextDefaultGPUFramebuffer(GHOST_ContextHandle contexthandle);

extern unsigned int GHOST_GetDefaultGPUFramebuffer(GHOST_WindowHandle windowhandle);

extern void GHOST_SetMultitouchGestures(GHOST_SystemHandle systemhandle, const bool use);

extern void GHOST_SetTabletAPI(GHOST_SystemHandle systemhandle, GHOST_TTabletAPI api);

extern GHOST_TSuccess GHOST_GetPixelAtCursor(float r_color[3]);

extern int32_t GHOST_GetWidthRectangle(GHOST_RectangleHandle rectanglehandle);

extern int32_t GHOST_GetHeightRectangle(GHOST_RectangleHandle rectanglehandle);

extern void GHOST_GetRectangle(
    GHOST_RectangleHandle rectanglehandle, int32_t *l, int32_t *t, int32_t *r, int32_t *b);

extern void GHOST_SetRectangle(
    GHOST_RectangleHandle rectanglehandle, int32_t l, int32_t t, int32_t r, int32_t b);

extern GHOST_TSuccess GHOST_IsEmptyRectangle(GHOST_RectangleHandle rectanglehandle);

extern GHOST_TSuccess GHOST_IsValidRectangle(GHOST_RectangleHandle rectanglehandle);

extern void GHOST_InsetRectangle(GHOST_RectangleHandle rectanglehandle, int32_t i);

extern void GHOST_UnionRectangle(GHOST_RectangleHandle rectanglehandle,
                                 GHOST_RectangleHandle anotherrectanglehandle);

extern void GHOST_UnionPointRectangle(GHOST_RectangleHandle rectanglehandle, int32_t x, int32_t y);

extern GHOST_TSuccess GHOST_IsInsideRectangle(GHOST_RectangleHandle rectanglehandle,
                                              int32_t x,
                                              int32_t y);

extern GHOST_TVisibility GHOST_GetRectangleVisibility(
    GHOST_RectangleHandle rectanglehandle, GHOST_RectangleHandle anotherrectanglehandle);

extern void GHOST_SetCenterRectangle(GHOST_RectangleHandle rectanglehandle,
                                     int32_t cx,
                                     int32_t cy);

extern void GHOST_SetRectangleCenter(
    GHOST_RectangleHandle rectanglehandle, int32_t cx, int32_t cy, int32_t w, int32_t h);

extern GHOST_TSuccess GHOST_ClipRectangle(GHOST_RectangleHandle rectanglehandle,
                                          GHOST_RectangleHandle anotherrectanglehandle);

extern char *GHOST_getClipboard(bool selection);

extern void GHOST_putClipboard(const char *buffer, bool selection);

extern GHOST_TSuccess GHOST_hasClipboardImage(void);

extern uint *GHOST_getClipboardImage(int *r_width, int *r_height);

extern GHOST_TSuccess GHOST_putClipboardImage(uint *rgba, int width, int height);

extern bool GHOST_setConsoleWindowState(GHOST_TConsoleWindowState action);

extern bool GHOST_UseNativePixels(void);

extern GHOST_TCapabilityFlag GHOST_GetCapabilities(void);

extern void GHOST_SetBacktraceHandler(GHOST_TBacktraceFn backtrace_fn);

extern void GHOST_UseWindowFrame(bool use_window_frame);

extern void GHOST_UseWindowFocus(bool use_focus);

extern void GHOST_SetAutoFocus(bool auto_focus);

extern float GHOST_GetNativePixelSize(GHOST_WindowHandle windowhandle);

extern uint16_t GHOST_GetDPIHint(GHOST_WindowHandle windowhandle);

extern void GHOST_BeginIME(
    GHOST_WindowHandle windowhandle, int32_t x, int32_t y, int32_t w, int32_t h, bool complete);
extern void GHOST_EndIME(GHOST_WindowHandle windowhandle);
 
#ifdef WITH_XR_OPENXR
 
/* XR-context */

void GHOST_XrErrorHandler(GHOST_XrErrorHandlerFn handler_fn, void *customdata);

GHOST_XrContextHandle GHOST_XrContextCreate(const GHOST_XrContextCreateInfo *create_info);
void GHOST_XrContextDestroy(GHOST_XrContextHandle xr_context);

void GHOST_XrGraphicsContextBindFuncs(GHOST_XrContextHandle xr_context,
                                      GHOST_XrGraphicsContextBindFn bind_fn,
                                      GHOST_XrGraphicsContextUnbindFn unbind_fn);

void GHOST_XrDrawViewFunc(GHOST_XrContextHandle xr_context, GHOST_XrDrawViewFn draw_view_fn);

void GHOST_XrPassthroughEnabledFunc(GHOST_XrContextHandle xr_context,
                                    GHOST_XrPassthroughEnabledFn passthrough_enabled_fn);

void GHOST_XrDisablePassthroughFunc(GHOST_XrContextHandle xr_context,
                                    GHOST_XrDisablePassthroughFn disable_passthrough_fn);
 
/* sessions */
void GHOST_XrSessionStart(GHOST_XrContextHandle xr_context,
                          const GHOST_XrSessionBeginInfo *begin_info);
void GHOST_XrSessionEnd(GHOST_XrContextHandle xr_context);
void GHOST_XrSessionDrawViews(GHOST_XrContextHandle xr_context, void *customdata);
int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_context);

int GHOST_XrSessionNeedsUpsideDownDrawing(const GHOST_XrContextHandle xr_context);
 
/* events */
GHOST_TSuccess GHOST_XrEventsHandle(GHOST_XrContextHandle xr_context);
 
/* actions */
int GHOST_XrCreateActionSet(GHOST_XrContextHandle xr_context, const GHOST_XrActionSetInfo *info);

void GHOST_XrDestroyActionSet(GHOST_XrContextHandle xr_context, const char *action_set_name);

int GHOST_XrCreateActions(GHOST_XrContextHandle xr_context,
                          const char *action_set_name,
                          uint32_t count,
                          const GHOST_XrActionInfo *infos);

void GHOST_XrDestroyActions(GHOST_XrContextHandle xr_context,
                            const char *action_set_name,
                            uint32_t count,
                            const char *const *action_names);

int GHOST_XrCreateActionBindings(GHOST_XrContextHandle xr_context,
                                 const char *action_set_name,
                                 uint32_t count,
                                 const GHOST_XrActionProfileInfo *infos);

void GHOST_XrDestroyActionBindings(GHOST_XrContextHandle xr_context,
                                   const char *action_set_name,
                                   uint32_t count,
                                   const char *const *action_names,
                                   const char *const *profile_paths);

int GHOST_XrAttachActionSets(GHOST_XrContextHandle xr_context);

int GHOST_XrSyncActions(GHOST_XrContextHandle xr_context, const char *action_set_name);

int GHOST_XrApplyHapticAction(GHOST_XrContextHandle xr_context_handle,
                              const char *action_set_name,
                              const char *action_name,
                              const char *subaction_path,
                              const int64_t *duration,
                              const float *frequency,
                              const float *amplitude);

void GHOST_XrStopHapticAction(GHOST_XrContextHandle xr_context_handle,
                              const char *action_set_name,
                              const char *action_name,
                              const char *subaction_path);

void *GHOST_XrGetActionSetCustomdata(GHOST_XrContextHandle xr_context,
                                     const char *action_set_name);

void *GHOST_XrGetActionCustomdata(GHOST_XrContextHandle xr_context,
                                  const char *action_set_name,
                                  const char *action_name);

unsigned int GHOST_XrGetActionCount(GHOST_XrContextHandle xr_context, const char *action_set_name);

void GHOST_XrGetActionCustomdataArray(GHOST_XrContextHandle xr_context,
                                      const char *action_set_name,
                                      void **r_customdata_array);
 
/* controller model */
int GHOST_XrLoadControllerModel(GHOST_XrContextHandle xr_context, const char *subaction_path);

void GHOST_XrUnloadControllerModel(GHOST_XrContextHandle xr_context, const char *subaction_path);

int GHOST_XrUpdateControllerModelComponents(GHOST_XrContextHandle xr_context,
                                            const char *subaction_path);

int GHOST_XrGetControllerModelData(GHOST_XrContextHandle xr_context,
                                   const char *subaction_path,
                                   GHOST_XrControllerModelData *r_data);
 
#endif /* WITH_XR_OPENXR */
 
#ifdef WITH_VULKAN_BACKEND

void GHOST_GetVulkanHandles(GHOST_ContextHandle context, GHOST_VulkanHandles *r_handles);

void GHOST_SetVulkanSwapBuffersCallbacks(
    GHOST_ContextHandle context,
    void (*swap_buffer_draw_callback)(const GHOST_VulkanSwapChainData *),
    void (*swap_buffer_acquired_callback)(void),
    void (*openxr_acquire_image_callback)(GHOST_VulkanOpenXRData *),
    void (*openxr_release_image_callback)(GHOST_VulkanOpenXRData *));

void GHOST_GetVulkanSwapChainFormat(GHOST_WindowHandle windowhandle,
                                    GHOST_VulkanSwapChainData *r_swap_chain_data);
 
#endif
 
#ifdef __cplusplus
}
 
#endif