1 /* 2 * This program is free software; you can redistribute it and/or 3 * modify it under the terms of the GNU General Public License 4 * as published by the Free Software Foundation; either version 2 5 * of the License, or (at your option) any later version. 6 * 7 * This program is distributed in the hope that it will be useful, 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 * GNU General Public License for more details. 11 * 12 * You should have received a copy of the GNU General Public License 13 * along with this program; if not, write to the Free Software Foundation, 14 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 15 * 16 * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV. 17 * All rights reserved. 18 */ 19 /** \file 20 * \ingroup GHOST 21 * \brief GHOST C-API function and type declarations. 22 */ 23 24 #pragma once 25 26 #include "GHOST_Types.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * Definition of a callback routine that receives events. 34 * \param event The event received. 35 * \param userdata The callback's user data, supplied to GHOST_CreateSystem. 36 */ 37 typedef int (*GHOST_EventCallbackProcPtr)(GHOST_EventHandle event, GHOST_TUserDataPtr userdata); 38 39 /** 40 * Creates the one and only system. 41 * \return a handle to the system. 42 */ 43 extern GHOST_SystemHandle GHOST_CreateSystem(void); 44 45 /** 46 * Specifies whether debug messages are to be enabled for the specific system handle. 47 */ 48 extern void GHOST_SystemInitDebug(GHOST_SystemHandle systemhandle, int is_debug_enabled); 49 50 /** 51 * Disposes the one and only system. 52 * \param systemhandle The handle to the system 53 * \return An indication of success. 54 */ 55 extern GHOST_TSuccess GHOST_DisposeSystem(GHOST_SystemHandle systemhandle); 56 57 /** 58 * Show a system message box to the user 59 * \param systemhandle The handle to the system 60 * \param title Title of the message box 61 * \param message Message of the message box 62 * \param help_label Text to show on the help button that opens a link 63 * \param continue_label Text to show on the ok button that continues 64 * \param link Optional (hyper)link to a webpage to show when pressing help 65 * \param dialog_options Options to configure the message box. 66 * \return void. 67 */ 68 extern void GHOST_ShowMessageBox(GHOST_SystemHandle systemhandle, 69 const char *title, 70 const char *message, 71 const char *help_label, 72 const char *continue_label, 73 const char *link, 74 GHOST_DialogOptions dialog_options); 75 76 /** 77 * Creates an event consumer object 78 * \param eventCallback The event callback routine. 79 * \param userdata Pointer to user data returned to the callback routine. 80 */ 81 extern GHOST_EventConsumerHandle GHOST_CreateEventConsumer( 82 GHOST_EventCallbackProcPtr eventCallback, GHOST_TUserDataPtr userdata); 83 84 /** 85 * Disposes an event consumer object 86 * \param consumerhandle Handle to the event consumer. 87 * \return An indication of success. 88 */ 89 extern GHOST_TSuccess GHOST_DisposeEventConsumer(GHOST_EventConsumerHandle consumerhandle); 90 91 /** 92 * Returns the system time. 93 * Returns the number of milliseconds since the start of the system process. 94 * Based on ANSI clock() routine. 95 * \param systemhandle The handle to the system 96 * \return The number of milliseconds. 97 */ 98 extern GHOST_TUns64 GHOST_GetMilliSeconds(GHOST_SystemHandle systemhandle); 99 100 /** 101 * Installs a timer. 102 * Note that, on most operating systems, messages need to be processed in order 103 * for the timer callbacks to be invoked. 104 * \param systemhandle The handle to the system 105 * \param delay The time to wait for the first call to the timerProc (in milliseconds) 106 * \param interval The interval between calls to the timerProc (in milliseconds) 107 * \param timerProc The callback invoked when the interval expires, 108 * \param userData Placeholder for user data. 109 * \return A timer task (0 if timer task installation failed). 110 */ 111 extern GHOST_TimerTaskHandle GHOST_InstallTimer(GHOST_SystemHandle systemhandle, 112 GHOST_TUns64 delay, 113 GHOST_TUns64 interval, 114 GHOST_TimerProcPtr timerProc, 115 GHOST_TUserDataPtr userData); 116 117 /** 118 * Removes a timer. 119 * \param systemhandle The handle to the system 120 * \param timertaskhandle Timer task to be removed. 121 * \return Indication of success. 122 */ 123 extern GHOST_TSuccess GHOST_RemoveTimer(GHOST_SystemHandle systemhandle, 124 GHOST_TimerTaskHandle timertaskhandle); 125 126 /*************************************************************************************** 127 * Display/window management functionality 128 ***************************************************************************************/ 129 130 /** 131 * Returns the number of displays on this system. 132 * \param systemhandle The handle to the system 133 * \return The number of displays. 134 */ 135 extern GHOST_TUns8 GHOST_GetNumDisplays(GHOST_SystemHandle systemhandle); 136 137 /** 138 * Returns the dimensions of the main display on this system. 139 * \param systemhandle The handle to the system 140 * \param width A pointer the width gets put in 141 * \param height A pointer the height gets put in 142 * \return void. 143 */ 144 extern void GHOST_GetMainDisplayDimensions(GHOST_SystemHandle systemhandle, 145 GHOST_TUns32 *width, 146 GHOST_TUns32 *height); 147 148 /** 149 * Returns the dimensions of all displays combine 150 * (the current workspace). 151 * No need to worry about overlapping monitors. 152 * \param systemhandle The handle to the system 153 * \param width A pointer the width gets put in 154 * \param height A pointer the height gets put in 155 * \return void. 156 */ 157 extern void GHOST_GetAllDisplayDimensions(GHOST_SystemHandle systemhandle, 158 GHOST_TUns32 *width, 159 GHOST_TUns32 *height); 160 161 /** 162 * Create a new window. 163 * The new window is added to the list of windows managed. 164 * Never explicitly delete the window, use disposeWindow() instead. 165 * \param systemhandle The handle to the system 166 * \param title The name of the window 167 * (displayed in the title bar of the window if the OS supports it). 168 * \param left The coordinate of the left edge of the window. 169 * \param top The coordinate of the top edge of the window. 170 * \param width The width the window. 171 * \param height The height the window. 172 * \param state The state of the window when opened. 173 * \param type The type of drawing context installed in this window. 174 * \param glSettings: Misc OpenGL options. 175 * \return A handle to the new window ( == NULL if creation failed). 176 */ 177 extern GHOST_WindowHandle GHOST_CreateWindow(GHOST_SystemHandle systemhandle, 178 const char *title, 179 GHOST_TInt32 left, 180 GHOST_TInt32 top, 181 GHOST_TUns32 width, 182 GHOST_TUns32 height, 183 GHOST_TWindowState state, 184 GHOST_TDrawingContextType type, 185 GHOST_GLSettings glSettings); 186 187 extern GHOST_WindowHandle GHOST_CreateDialogWindow(GHOST_SystemHandle systemhandle, 188 GHOST_WindowHandle parent_windowhandle, 189 const char *title, 190 GHOST_TInt32 left, 191 GHOST_TInt32 top, 192 GHOST_TUns32 width, 193 GHOST_TUns32 height, 194 GHOST_TWindowState state, 195 GHOST_TDrawingContextType type, 196 GHOST_GLSettings glSettings); 197 198 /** 199 * Create a new offscreen context. 200 * Never explicitly delete the context, use disposeContext() instead. 201 * \param systemhandle The handle to the system 202 * \param platform_support_callback An optional callback to check platform support 203 * \return A handle to the new context ( == NULL if creation failed). 204 */ 205 extern GHOST_ContextHandle GHOST_CreateOpenGLContext(GHOST_SystemHandle systemhandle, 206 GHOST_GLSettings glSettings); 207 208 /** 209 * Dispose of a context. 210 * \param systemhandle The handle to the system 211 * \param contexthandle Handle to the context to be disposed. 212 * \return Indication of success. 213 */ 214 extern GHOST_TSuccess GHOST_DisposeOpenGLContext(GHOST_SystemHandle systemhandle, 215 GHOST_ContextHandle contexthandle); 216 217 /** 218 * Returns the window user data. 219 * \param windowhandle The handle to the window 220 * \return The window user data. 221 */ 222 extern GHOST_TUserDataPtr GHOST_GetWindowUserData(GHOST_WindowHandle windowhandle); 223 224 /** 225 * Changes the window user data. 226 * \param windowhandle The handle to the window 227 * \param userdata The window user data. 228 */ 229 extern void GHOST_SetWindowUserData(GHOST_WindowHandle windowhandle, GHOST_TUserDataPtr userdata); 230 231 extern int GHOST_IsDialogWindow(GHOST_WindowHandle windowhandle); 232 233 /** 234 * Dispose a window. 235 * \param systemhandle The handle to the system 236 * \param windowhandle Handle to the window to be disposed. 237 * \return Indication of success. 238 */ 239 extern GHOST_TSuccess GHOST_DisposeWindow(GHOST_SystemHandle systemhandle, 240 GHOST_WindowHandle windowhandle); 241 242 /** 243 * Returns whether a window is valid. 244 * \param systemhandle The handle to the system 245 * \param windowhandle Handle to the window to be checked. 246 * \return Indication of validity. 247 */ 248 extern int GHOST_ValidWindow(GHOST_SystemHandle systemhandle, GHOST_WindowHandle windowhandle); 249 250 /** 251 * Begins full screen mode. 252 * \param systemhandle The handle to the system 253 * \param setting The new setting of the display. 254 * \param stereoVisual Option for stereo display. 255 * \return A handle to the window displayed in full screen. 256 * This window is invalid after full screen has been ended. 257 */ 258 extern GHOST_WindowHandle GHOST_BeginFullScreen(GHOST_SystemHandle systemhandle, 259 GHOST_DisplaySetting *setting, 260 const int stereoVisual); 261 262 /** 263 * Ends full screen mode. 264 * \param systemhandle The handle to the system 265 * \return Indication of success. 266 */ 267 extern GHOST_TSuccess GHOST_EndFullScreen(GHOST_SystemHandle systemhandle); 268 269 /** 270 * Returns current full screen mode status. 271 * \param systemhandle The handle to the system 272 * \return The current status. 273 */ 274 extern int GHOST_GetFullScreen(GHOST_SystemHandle systemhandle); 275 276 /*************************************************************************************** 277 * Event management functionality 278 ***************************************************************************************/ 279 280 /** 281 * Retrieves events from the system and stores them in the queue. 282 * \param systemhandle The handle to the system 283 * \param waitForEvent Boolean to indicate that ProcessEvents should 284 * wait (block) until the next event before returning. 285 * \return Indication of the presence of events. 286 */ 287 extern int GHOST_ProcessEvents(GHOST_SystemHandle systemhandle, int waitForEvent); 288 289 /** 290 * Retrieves events from the queue and send them to the event consumers. 291 * \param systemhandle The handle to the system 292 */ 293 extern void GHOST_DispatchEvents(GHOST_SystemHandle systemhandle); 294 295 /** 296 * Adds the given event consumer to our list. 297 * \param systemhandle The handle to the system 298 * \param consumerhandle The event consumer to add. 299 * \return Indication of success. 300 */ 301 extern GHOST_TSuccess GHOST_AddEventConsumer(GHOST_SystemHandle systemhandle, 302 GHOST_EventConsumerHandle consumerhandle); 303 304 /** 305 * Remove the given event consumer to our list. 306 * \param systemhandle The handle to the system 307 * \param consumerhandle The event consumer to remove. 308 * \return Indication of success. 309 */ 310 extern GHOST_TSuccess GHOST_RemoveEventConsumer(GHOST_SystemHandle systemhandle, 311 GHOST_EventConsumerHandle consumerhandle); 312 313 /*************************************************************************************** 314 * Progress bar functionality 315 ***************************************************************************************/ 316 317 /** 318 * Sets the progress bar value displayed in the window/application icon 319 * \param windowhandle The handle to the window 320 * \param progress The progress % (0.0 to 1.0) 321 */ 322 extern GHOST_TSuccess GHOST_SetProgressBar(GHOST_WindowHandle windowhandle, float progress); 323 324 /** 325 * Hides the progress bar in the icon 326 * \param windowhandle The handle to the window 327 */ 328 extern GHOST_TSuccess GHOST_EndProgressBar(GHOST_WindowHandle windowhandle); 329 330 /*************************************************************************************** 331 * Cursor management functionality 332 ***************************************************************************************/ 333 334 /** 335 * Returns the current cursor shape. 336 * \param windowhandle The handle to the window 337 * \return The current cursor shape. 338 */ 339 extern GHOST_TStandardCursor GHOST_GetCursorShape(GHOST_WindowHandle windowhandle); 340 341 /** 342 * Set the shape of the cursor. If the shape is not supported by the platform, 343 * it will use the default cursor instead. 344 * \param windowhandle The handle to the window 345 * \param cursorshape The new cursor shape type id. 346 * \return Indication of success. 347 */ 348 extern GHOST_TSuccess GHOST_SetCursorShape(GHOST_WindowHandle windowhandle, 349 GHOST_TStandardCursor cursorshape); 350 351 /** 352 * Test if the standard cursor shape is supported by current platform. 353 * \return Indication of success. 354 */ 355 extern GHOST_TSuccess GHOST_HasCursorShape(GHOST_WindowHandle windowhandle, 356 GHOST_TStandardCursor cursorshape); 357 358 /** 359 * Set the shape of the cursor to a custom cursor of specified size. 360 * \param windowhandle The handle to the window 361 * \param bitmap The bitmap data for the cursor. 362 * \param mask The mask data for the cursor. 363 * \param sizex The width of the cursor 364 * \param sizey The height of the cursor 365 * \param hotX The X coordinate of the cursor hot-spot. 366 * \param hotY The Y coordinate of the cursor hot-spot. 367 * \param canInvertColor Let macOS invert cursor color to match platform convention. 368 * \return Indication of success. 369 */ 370 extern GHOST_TSuccess GHOST_SetCustomCursorShape(GHOST_WindowHandle windowhandle, 371 GHOST_TUns8 *bitmap, 372 GHOST_TUns8 *mask, 373 int sizex, 374 int sizey, 375 int hotX, 376 int hotY, 377 GHOST_TUns8 canInvertColor); 378 379 /** 380 * Returns the visibility state of the cursor. 381 * \param windowhandle The handle to the window 382 * \return The visibility state of the cursor. 383 */ 384 extern int GHOST_GetCursorVisibility(GHOST_WindowHandle windowhandle); 385 386 /** 387 * Shows or hides the cursor. 388 * \param windowhandle The handle to the window 389 * \param visible The new visibility state of the cursor. 390 * \return Indication of success. 391 */ 392 extern GHOST_TSuccess GHOST_SetCursorVisibility(GHOST_WindowHandle windowhandle, int visible); 393 394 /** 395 * Returns the current location of the cursor (location in screen coordinates) 396 * \param systemhandle The handle to the system 397 * \param x The x-coordinate of the cursor. 398 * \param y The y-coordinate of the cursor. 399 * \return Indication of success. 400 */ 401 extern GHOST_TSuccess GHOST_GetCursorPosition(GHOST_SystemHandle systemhandle, 402 GHOST_TInt32 *x, 403 GHOST_TInt32 *y); 404 405 /** 406 * Updates the location of the cursor (location in screen coordinates). 407 * Not all operating systems allow the cursor to be moved (without the input device being moved). 408 * \param systemhandle The handle to the system 409 * \param x The x-coordinate of the cursor. 410 * \param y The y-coordinate of the cursor. 411 * \return Indication of success. 412 */ 413 extern GHOST_TSuccess GHOST_SetCursorPosition(GHOST_SystemHandle systemhandle, 414 GHOST_TInt32 x, 415 GHOST_TInt32 y); 416 417 /** 418 * Grabs the cursor for a modal operation, to keep receiving 419 * events when the mouse is outside the window. X11 only, others 420 * do this automatically. 421 * \param windowhandle The handle to the window 422 * \param mode The new grab state of the cursor. 423 * \param bounds The grab region (optional) - left,top,right,bottom 424 * \param mouse_ungrab_xy XY for new mouse location (optional) - x,y 425 * \return Indication of success. 426 */ 427 extern GHOST_TSuccess GHOST_SetCursorGrab(GHOST_WindowHandle windowhandle, 428 GHOST_TGrabCursorMode mode, 429 GHOST_TAxisFlag warp_axis, 430 int bounds[4], 431 const int mouse_ungrab_xy[2]); 432 433 /*************************************************************************************** 434 * Access to mouse button and keyboard states. 435 ***************************************************************************************/ 436 437 /** 438 * Returns the state of a modifier key (outside the message queue). 439 * \param systemhandle The handle to the system 440 * \param mask The modifier key state to retrieve. 441 * \param isDown Pointer to return modifier state in. 442 * \return Indication of success. 443 */ 444 extern GHOST_TSuccess GHOST_GetModifierKeyState(GHOST_SystemHandle systemhandle, 445 GHOST_TModifierKeyMask mask, 446 int *isDown); 447 448 /** 449 * Returns the state of a mouse button (outside the message queue). 450 * \param systemhandle The handle to the system 451 * \param mask The button state to retrieve. 452 * \param isDown Pointer to return button state in. 453 * \return Indication of success. 454 */ 455 extern GHOST_TSuccess GHOST_GetButtonState(GHOST_SystemHandle systemhandle, 456 GHOST_TButtonMask mask, 457 int *isDown); 458 459 #ifdef WITH_INPUT_NDOF 460 /*************************************************************************************** 461 * Access to 3D mouse. 462 ***************************************************************************************/ 463 464 /** 465 * Sets 3D mouse dead-zone. 466 * \param deadzone: Dead-zone of the 3D mouse (both for rotation and pan) relative to full range. 467 */ 468 extern void GHOST_setNDOFDeadZone(float deadzone); 469 #endif 470 471 /*************************************************************************************** 472 * Drag'n'drop operations 473 ***************************************************************************************/ 474 475 /** 476 * Tells if the ongoing drag'n'drop object can be accepted upon mouse drop 477 */ 478 extern void GHOST_setAcceptDragOperation(GHOST_WindowHandle windowhandle, GHOST_TInt8 canAccept); 479 480 /** 481 * Returns the event type. 482 * \param eventhandle The handle to the event 483 * \return The event type. 484 */ 485 extern GHOST_TEventType GHOST_GetEventType(GHOST_EventHandle eventhandle); 486 487 /** 488 * Returns the time this event was generated. 489 * \param eventhandle The handle to the event 490 * \return The event generation time. 491 */ 492 extern GHOST_TUns64 GHOST_GetEventTime(GHOST_EventHandle eventhandle); 493 494 /** 495 * Returns the window this event was generated on, 496 * or NULL if it is a 'system' event. 497 * \param eventhandle The handle to the event 498 * \return The generating window. 499 */ 500 extern GHOST_WindowHandle GHOST_GetEventWindow(GHOST_EventHandle eventhandle); 501 502 /** 503 * Returns the event data. 504 * \param eventhandle The handle to the event 505 * \return The event data. 506 */ 507 extern GHOST_TEventDataPtr GHOST_GetEventData(GHOST_EventHandle eventhandle); 508 509 /** 510 * Returns the timer callback. 511 * \param timertaskhandle The handle to the timer-task. 512 * \return The timer callback. 513 */ 514 extern GHOST_TimerProcPtr GHOST_GetTimerProc(GHOST_TimerTaskHandle timertaskhandle); 515 516 /** 517 * Changes the timer callback. 518 * \param timertaskhandle The handle to the timertask 519 * \param timerProc The timer callback. 520 */ 521 extern void GHOST_SetTimerProc(GHOST_TimerTaskHandle timertaskhandle, 522 GHOST_TimerProcPtr timerProc); 523 524 /** 525 * Returns the timer user data. 526 * \param timertaskhandle The handle to the timertask 527 * \return The timer user data. 528 */ 529 extern GHOST_TUserDataPtr GHOST_GetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle); 530 531 /** 532 * Changes the time user data. 533 * \param timertaskhandle The handle to the timertask 534 * \param userdata The timer user data. 535 */ 536 extern void GHOST_SetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle, 537 GHOST_TUserDataPtr userdata); 538 539 /** 540 * Returns indication as to whether the window is valid. 541 * \param windowhandle The handle to the window 542 * \return The validity of the window. 543 */ 544 extern int GHOST_GetValid(GHOST_WindowHandle windowhandle); 545 546 /** 547 * Returns the type of drawing context used in this window. 548 * \param windowhandle The handle to the window 549 * \return The current type of drawing context. 550 */ 551 extern GHOST_TDrawingContextType GHOST_GetDrawingContextType(GHOST_WindowHandle windowhandle); 552 553 /** 554 * Tries to install a rendering context in this window. 555 * \param windowhandle The handle to the window 556 * \param type The type of rendering context installed. 557 * \return Indication as to whether installation has succeeded. 558 */ 559 extern GHOST_TSuccess GHOST_SetDrawingContextType(GHOST_WindowHandle windowhandle, 560 GHOST_TDrawingContextType type); 561 562 /** 563 * Sets the title displayed in the title bar. 564 * \param windowhandle The handle to the window 565 * \param title The title to display in the title bar. 566 */ 567 extern void GHOST_SetTitle(GHOST_WindowHandle windowhandle, const char *title); 568 569 /** 570 * Returns the title displayed in the title bar. The title 571 * should be free'd with free(). 572 * 573 * \param windowhandle The handle to the window 574 * \return The title, free with free(). 575 */ 576 extern char *GHOST_GetTitle(GHOST_WindowHandle windowhandle); 577 578 /** 579 * Returns the window rectangle dimensions. 580 * These are screen coordinates. 581 * \param windowhandle The handle to the window 582 * \return A handle to the bounding rectangle of the window. 583 */ 584 extern GHOST_RectangleHandle GHOST_GetWindowBounds(GHOST_WindowHandle windowhandle); 585 586 /** 587 * Returns the client rectangle dimensions. 588 * The left and top members of the rectangle are always zero. 589 * \param windowhandle The handle to the window 590 * \return A handle to the bounding rectangle of the window. 591 */ 592 extern GHOST_RectangleHandle GHOST_GetClientBounds(GHOST_WindowHandle windowhandle); 593 594 /** 595 * Disposes a rectangle object 596 * \param rectanglehandle Handle to the rectangle. 597 */ 598 void GHOST_DisposeRectangle(GHOST_RectangleHandle rectanglehandle); 599 600 /** 601 * Resizes client rectangle width. 602 * \param windowhandle The handle to the window 603 * \param width The new width of the client area of the window. 604 * \return Indication of success. 605 */ 606 extern GHOST_TSuccess GHOST_SetClientWidth(GHOST_WindowHandle windowhandle, GHOST_TUns32 width); 607 608 /** 609 * Resizes client rectangle height. 610 * \param windowhandle The handle to the window 611 * \param height The new height of the client area of the window. 612 * \return Indication of success. 613 */ 614 extern GHOST_TSuccess GHOST_SetClientHeight(GHOST_WindowHandle windowhandle, GHOST_TUns32 height); 615 616 /** 617 * Resizes client rectangle. 618 * \param windowhandle The handle to the window 619 * \param width The new width of the client area of the window. 620 * \param height The new height of the client area of the window. 621 * \return Indication of success. 622 */ 623 extern GHOST_TSuccess GHOST_SetClientSize(GHOST_WindowHandle windowhandle, 624 GHOST_TUns32 width, 625 GHOST_TUns32 height); 626 627 /** 628 * Converts a point in screen coordinates to client rectangle coordinates 629 * \param windowhandle The handle to the window 630 * \param inX The x-coordinate on the screen. 631 * \param inY The y-coordinate on the screen. 632 * \param outX The x-coordinate in the client rectangle. 633 * \param outY The y-coordinate in the client rectangle. 634 */ 635 extern void GHOST_ScreenToClient(GHOST_WindowHandle windowhandle, 636 GHOST_TInt32 inX, 637 GHOST_TInt32 inY, 638 GHOST_TInt32 *outX, 639 GHOST_TInt32 *outY); 640 641 /** 642 * Converts a point in screen coordinates to client rectangle coordinates 643 * \param windowhandle The handle to the window 644 * \param inX The x-coordinate in the client rectangle. 645 * \param inY The y-coordinate in the client rectangle. 646 * \param outX The x-coordinate on the screen. 647 * \param outY The y-coordinate on the screen. 648 */ 649 extern void GHOST_ClientToScreen(GHOST_WindowHandle windowhandle, 650 GHOST_TInt32 inX, 651 GHOST_TInt32 inY, 652 GHOST_TInt32 *outX, 653 GHOST_TInt32 *outY); 654 655 /** 656 * Returns the state of the window (normal, minimized, maximized). 657 * \param windowhandle The handle to the window 658 * \return The state of the window. 659 */ 660 extern GHOST_TWindowState GHOST_GetWindowState(GHOST_WindowHandle windowhandle); 661 662 /** 663 * Sets the state of the window (normal, minimized, maximized). 664 * \param windowhandle The handle to the window 665 * \param state The state of the window. 666 * \return Indication of success. 667 */ 668 extern GHOST_TSuccess GHOST_SetWindowState(GHOST_WindowHandle windowhandle, 669 GHOST_TWindowState state); 670 671 /** 672 * Sets the window "modified" status, indicating unsaved changes 673 * \param windowhandle The handle to the window 674 * \param isUnsavedChanges Unsaved changes or not 675 * \return Indication of success. 676 */ 677 extern GHOST_TSuccess GHOST_SetWindowModifiedState(GHOST_WindowHandle windowhandle, 678 GHOST_TUns8 isUnsavedChanges); 679 680 /** 681 * Sets the order of the window (bottom, top). 682 * \param windowhandle The handle to the window 683 * \param order The order of the window. 684 * \return Indication of success. 685 */ 686 extern GHOST_TSuccess GHOST_SetWindowOrder(GHOST_WindowHandle windowhandle, 687 GHOST_TWindowOrder order); 688 689 /** 690 * Swaps front and back buffers of a window. 691 * \param windowhandle The handle to the window 692 * \return A success indicator. 693 */ 694 extern GHOST_TSuccess GHOST_SwapWindowBuffers(GHOST_WindowHandle windowhandle); 695 696 /** 697 * Sets the swap interval for swapBuffers. 698 * \param interval The swap interval to use. 699 * \return A boolean success indicator. 700 */ 701 extern GHOST_TSuccess GHOST_SetSwapInterval(GHOST_WindowHandle windowhandle, int interval); 702 703 /** 704 * Gets the current swap interval for swapBuffers. 705 * \param windowhandle: The handle to the window 706 * \param intervalOut: pointer to location to return swap interval 707 * (left untouched if there is an error) 708 * \return A boolean success indicator of if swap interval was successfully read. 709 */ 710 extern GHOST_TSuccess GHOST_GetSwapInterval(GHOST_WindowHandle windowhandle, int *intervalOut); 711 712 /** 713 * Activates the drawing context of this window. 714 * \param windowhandle The handle to the window 715 * \return A success indicator. 716 */ 717 extern GHOST_TSuccess GHOST_ActivateWindowDrawingContext(GHOST_WindowHandle windowhandle); 718 719 /** 720 * Invalidates the contents of this window. 721 * \param windowhandle The handle to the window 722 * \return Indication of success. 723 */ 724 extern GHOST_TSuccess GHOST_InvalidateWindow(GHOST_WindowHandle windowhandle); 725 726 /** 727 * Activates the drawing context of this context. 728 * \param contexthandle The handle to the context 729 * \return A success indicator. 730 */ 731 extern GHOST_TSuccess GHOST_ActivateOpenGLContext(GHOST_ContextHandle contexthandle); 732 733 /** 734 * Release the drawing context bound to this thread. 735 * \param contexthandle The handle to the context 736 * \return A success indicator. 737 */ 738 extern GHOST_TSuccess GHOST_ReleaseOpenGLContext(GHOST_ContextHandle contexthandle); 739 740 /** 741 * Get the OpenGL frame-buffer handle that serves as a default frame-buffer. 742 */ 743 extern unsigned int GHOST_GetContextDefaultOpenGLFramebuffer(GHOST_ContextHandle contexthandle); 744 745 /** 746 * Returns whether a context is rendered upside down compared to OpenGL. This only needs to be 747 * called if there's a non-OpenGL context, which is really the exception. 748 * So generally, this does not need to be called. 749 */ 750 extern int GHOST_isUpsideDownContext(GHOST_ContextHandle contexthandle); 751 752 /** 753 * Get the OpenGL frame-buffer handle that serves as a default frame-buffer. 754 */ 755 extern unsigned int GHOST_GetDefaultOpenGLFramebuffer(GHOST_WindowHandle windwHandle); 756 757 /** 758 * Set which tablet API to use. Only affects Windows, other platforms have a single API. 759 * \param systemhandle The handle to the system 760 * \param api Enum indicating which API to use. 761 */ 762 extern void GHOST_SetTabletAPI(GHOST_SystemHandle systemhandle, GHOST_TTabletAPI api); 763 764 /** 765 * Access to rectangle width. 766 * \param rectanglehandle The handle to the rectangle 767 * \return width of the rectangle 768 */ 769 extern GHOST_TInt32 GHOST_GetWidthRectangle(GHOST_RectangleHandle rectanglehandle); 770 771 /** 772 * Access to rectangle height. 773 * \param rectanglehandle The handle to the rectangle 774 * \return height of the rectangle 775 */ 776 extern GHOST_TInt32 GHOST_GetHeightRectangle(GHOST_RectangleHandle rectanglehandle); 777 778 /** 779 * Gets all members of the rectangle. 780 * \param rectanglehandle The handle to the rectangle 781 * \param l Pointer to return left coordinate in. 782 * \param t Pointer to return top coordinate in. 783 * \param r Pointer to return right coordinate in. 784 * \param b Pointer to return bottom coordinate in. 785 */ 786 extern void GHOST_GetRectangle(GHOST_RectangleHandle rectanglehandle, 787 GHOST_TInt32 *l, 788 GHOST_TInt32 *t, 789 GHOST_TInt32 *r, 790 GHOST_TInt32 *b); 791 792 /** 793 * Sets all members of the rectangle. 794 * \param rectanglehandle The handle to the rectangle 795 * \param l requested left coordinate of the rectangle 796 * \param t requested top coordinate of the rectangle 797 * \param r requested right coordinate of the rectangle 798 * \param b requested bottom coordinate of the rectangle 799 */ 800 extern void GHOST_SetRectangle(GHOST_RectangleHandle rectanglehandle, 801 GHOST_TInt32 l, 802 GHOST_TInt32 t, 803 GHOST_TInt32 r, 804 GHOST_TInt32 b); 805 806 /** 807 * Returns whether this rectangle is empty. 808 * Empty rectangles are rectangles that have width==0 and/or height==0. 809 * \param rectanglehandle The handle to the rectangle 810 * \return Success value (true == empty rectangle) 811 */ 812 extern GHOST_TSuccess GHOST_IsEmptyRectangle(GHOST_RectangleHandle rectanglehandle); 813 814 /** 815 * Returns whether this rectangle is valid. 816 * Valid rectangles are rectangles that have m_l <= m_r and m_t <= m_b. 817 * Thus, empty rectangles are valid. 818 * \param rectanglehandle The handle to the rectangle 819 * \return Success value (true == valid rectangle) 820 */ 821 extern GHOST_TSuccess GHOST_IsValidRectangle(GHOST_RectangleHandle rectanglehandle); 822 823 /** 824 * Grows (or shrinks the rectangle). 825 * The method avoids negative insets making the rectangle invalid 826 * \param rectanglehandle The handle to the rectangle 827 * \param i The amount of offset given to each extreme (negative values shrink the rectangle). 828 */ 829 extern void GHOST_InsetRectangle(GHOST_RectangleHandle rectanglehandle, GHOST_TInt32 i); 830 831 /** 832 * Does a union of the rectangle given and this rectangle. 833 * The result is stored in this rectangle. 834 * \param rectanglehandle The handle to the rectangle 835 * \param anotherrectanglehandle The rectangle that is input for the union operation. 836 */ 837 extern void GHOST_UnionRectangle(GHOST_RectangleHandle rectanglehandle, 838 GHOST_RectangleHandle anotherrectanglehandle); 839 840 /** 841 * Grows the rectangle to included a point. 842 * \param rectanglehandle The handle to the rectangle 843 * \param x The x-coordinate of the point. 844 * \param y The y-coordinate of the point. 845 */ 846 extern void GHOST_UnionPointRectangle(GHOST_RectangleHandle rectanglehandle, 847 GHOST_TInt32 x, 848 GHOST_TInt32 y); 849 850 /** 851 * Returns whether the point is inside this rectangle. 852 * Point on the boundary is considered inside. 853 * \param rectanglehandle The handle to the rectangle 854 * \param x x-coordinate of point to test. 855 * \param y y-coordinate of point to test. 856 * \return Success value (true if point is inside). 857 */ 858 extern GHOST_TSuccess GHOST_IsInsideRectangle(GHOST_RectangleHandle rectanglehandle, 859 GHOST_TInt32 x, 860 GHOST_TInt32 y); 861 862 /** 863 * Returns whether the rectangle is inside this rectangle. 864 * \param rectanglehandle The handle to the rectangle 865 * \param anotherrectanglehandle The rectangle to test. 866 * \return visibility (not, partially or fully visible). 867 */ 868 extern GHOST_TVisibility GHOST_GetRectangleVisibility( 869 GHOST_RectangleHandle rectanglehandle, GHOST_RectangleHandle anotherrectanglehandle); 870 871 /** 872 * Sets rectangle members. 873 * Sets rectangle members such that it is centered at the given location. 874 * \param rectanglehandle The handle to the rectangle 875 * \param cx Requested center x-coordinate of the rectangle 876 * \param cy Requested center y-coordinate of the rectangle 877 */ 878 extern void GHOST_SetCenterRectangle(GHOST_RectangleHandle rectanglehandle, 879 GHOST_TInt32 cx, 880 GHOST_TInt32 cy); 881 882 /** 883 * Sets rectangle members. 884 * Sets rectangle members such that it is centered at the given location, 885 * with the width requested. 886 * \param rectanglehandle The handle to the rectangle 887 * \param cx requested center x-coordinate of the rectangle 888 * \param cy requested center y-coordinate of the rectangle 889 * \param w requested width of the rectangle 890 * \param h requested height of the rectangle 891 */ 892 extern void GHOST_SetRectangleCenter(GHOST_RectangleHandle rectanglehandle, 893 GHOST_TInt32 cx, 894 GHOST_TInt32 cy, 895 GHOST_TInt32 w, 896 GHOST_TInt32 h); 897 898 /** 899 * Clips a rectangle. 900 * Updates the rectangle given such that it will fit within this one. 901 * This can result in an empty rectangle. 902 * \param rectanglehandle The handle to the rectangle 903 * \param anotherrectanglehandle The rectangle to clip 904 * \return Whether clipping has occurred 905 */ 906 extern GHOST_TSuccess GHOST_ClipRectangle(GHOST_RectangleHandle rectanglehandle, 907 GHOST_RectangleHandle anotherrectanglehandle); 908 909 /** 910 * Return the data from the clipboard 911 * \param selection Boolean to return the selection instead, X11 only feature. 912 * \return clipboard data 913 */ 914 extern GHOST_TUns8 *GHOST_getClipboard(int selection); 915 916 /** 917 * Put data to the Clipboard 918 * \param buffer the string buffer to set. 919 * \param selection Set the selection instead, X11 only feature. 920 */ 921 extern void GHOST_putClipboard(GHOST_TInt8 *buffer, int selection); 922 923 /** 924 * Toggles console 925 * \param action 926 * - 0: Hides 927 * - 1: Shows 928 * - 2: Toggles 929 * - 3: Hides if it runs not from command line 930 * - *: Does nothing 931 * \return current status (1 -visible, 0 - hidden) 932 */ 933 extern int GHOST_toggleConsole(int action); 934 935 /** 936 * Use native pixel size (MacBook pro 'retina'), if supported. 937 */ 938 extern int GHOST_UseNativePixels(void); 939 940 /** 941 * Focus window after opening, or put them in the background. 942 */ 943 extern void GHOST_UseWindowFocus(int use_focus); 944 945 /** 946 * If window was opened using native pixel size, it returns scaling factor. 947 */ 948 extern float GHOST_GetNativePixelSize(GHOST_WindowHandle windowhandle); 949 950 /** 951 * Returns the suggested DPI for this window. 952 */ 953 extern GHOST_TUns16 GHOST_GetDPIHint(GHOST_WindowHandle windowhandle); 954 955 /** 956 * Enable IME attached to the given window, i.e. allows user-input 957 * events to be dispatched to the IME. 958 * \param windowhandle Window handle of the caller 959 * \param x Requested x-coordinate of the rectangle 960 * \param y Requested y-coordinate of the rectangle 961 * \param w Requested width of the rectangle 962 * \param h Requested height of the rectangle 963 * \param complete Whether or not to complete the ongoing composition 964 * true: Start a new composition 965 * false: Move the IME windows to the given position without finishing it. 966 */ 967 extern void GHOST_BeginIME(GHOST_WindowHandle windowhandle, 968 GHOST_TInt32 x, 969 GHOST_TInt32 y, 970 GHOST_TInt32 w, 971 GHOST_TInt32 h, 972 int complete); 973 /** 974 * Disable the IME attached to the given window, i.e. prohibits any user-input 975 * events from being dispatched to the IME. 976 * \param windowhandle The window handle of the caller 977 */ 978 extern void GHOST_EndIME(GHOST_WindowHandle windowhandle); 979 980 #ifdef WITH_XR_OPENXR 981 982 /* XR-context */ 983 984 /** 985 * Set a custom callback to be executed whenever an error occurs. Should be set before calling 986 * #GHOST_XrContextCreate() to get error handling during context creation too. 987 * 988 * \param customdata: Handle to some data that will get passed to \a handler_fn should an error be 989 * thrown. 990 */ 991 void GHOST_XrErrorHandler(GHOST_XrErrorHandlerFn handler_fn, void *customdata); 992 993 /** 994 * \brief Initialize the Ghost XR-context. 995 * 996 * Includes setting up the OpenXR runtime link, querying available extensions and API layers, 997 * enabling extensions and API layers. 998 * 999 * \param create_info: Options for creating the XR-context, e.g. debug-flags and ordered array of 1000 * graphics bindings to try enabling. 1001 */ 1002 GHOST_XrContextHandle GHOST_XrContextCreate(const GHOST_XrContextCreateInfo *create_info); 1003 /** 1004 * Free a XR-context involving OpenXR runtime link destruction and freeing of all internal data. 1005 */ 1006 void GHOST_XrContextDestroy(GHOST_XrContextHandle xr_context); 1007 1008 /** 1009 * Set callbacks for binding and unbinding a graphics context for a session. The binding callback 1010 * may create a new graphics context thereby. In fact that's the sole reason for this callback 1011 * approach to binding. Just make sure to have an unbind function set that properly destructs. 1012 * 1013 * \param bind_fn: Function to retrieve (possibly create) a graphics context. 1014 * \param unbind_fn: Function to release (possibly free) a graphics context. 1015 */ 1016 void GHOST_XrGraphicsContextBindFuncs(GHOST_XrContextHandle xr_context, 1017 GHOST_XrGraphicsContextBindFn bind_fn, 1018 GHOST_XrGraphicsContextUnbindFn unbind_fn); 1019 1020 /** 1021 * Set the drawing callback for views. A view would typically be either the left or the right eye, 1022 * although other configurations are possible. When #GHOST_XrSessionDrawViews() is called to draw 1023 * an XR frame, \a draw_view_fn is executed for each view. 1024 * 1025 * \param draw_view_fn: The callback to draw a single view for an XR frame. 1026 */ 1027 void GHOST_XrDrawViewFunc(GHOST_XrContextHandle xr_context, GHOST_XrDrawViewFn draw_view_fn); 1028 1029 /* sessions */ 1030 /** 1031 * Create internal session data for \a xr_context and ask the OpenXR runtime to invoke a session. 1032 * 1033 * \param begin_info: Options for the session creation. 1034 */ 1035 void GHOST_XrSessionStart(GHOST_XrContextHandle xr_context, 1036 const GHOST_XrSessionBeginInfo *begin_info); 1037 /** 1038 * Destruct internal session data for \a xr_context and ask the OpenXR runtime to stop a session. 1039 */ 1040 void GHOST_XrSessionEnd(GHOST_XrContextHandle xr_context); 1041 /** 1042 * Draw a single frame by calling the view drawing callback defined by #GHOST_XrDrawViewFunc() for 1043 * each view and submit it to the OpenXR runtime. 1044 * 1045 * \param customdata: Handle to some data that will get passed to the view drawing callback. 1046 */ 1047 void GHOST_XrSessionDrawViews(GHOST_XrContextHandle xr_context, void *customdata); 1048 /** 1049 * Check if a \a xr_context has a session that, according to the OpenXR definition would be 1050 * considered to be 'running' 1051 * (https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#session_running). 1052 */ 1053 int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_context); 1054 1055 /** 1056 * Check if \a xr_context has a session that requires an upside-down frame-buffer (compared to 1057 * OpenGL). If true, the render result should be flipped vertically for correct output. 1058 * \note: Only to be called after session start, may otherwise result in a false negative. 1059 */ 1060 int GHOST_XrSessionNeedsUpsideDownDrawing(const GHOST_XrContextHandle xr_context); 1061 1062 /* events */ 1063 /** 1064 * Invoke handling of all OpenXR events for \a xr_context. Should be called on every main-loop 1065 * iteration and will early-exit if \a xr_context is NULL (so caller doesn't have to check). 1066 * 1067 * \returns GHOST_kSuccess if any event was handled, otherwise GHOST_kFailure. 1068 */ 1069 GHOST_TSuccess GHOST_XrEventsHandle(GHOST_XrContextHandle xr_context); 1070 #endif 1071 1072 #ifdef __cplusplus 1073 } 1074 #endif 1075