doc/backends.txt

   1 Drawing Backends
   2 ----------------
   3
   4 Drawing backends provide means to draw on computer screen or into a window.
   5 Instead of having one unified initialization interface each backend has it's
   6 specific function and semantics but once backend is initialized the backend
   7 structure provides unified API for controlling the drawing.
   8
   9 TIP: For example usage see backend link:example_backend.html[example].
  10
  11 Supported backends
  12 ------------------
  13
  14 * Linux mmaped 'frame-buffer'
  15 * link:http://www.libsdl.org/[SDL]
  16 * 'X Window System'
  17 * link:http://aa-project.sourceforge.net/aalib/[AA-lib]
  18
  19
  20 Initialization functions
  21 ------------------------
  22
  23 Linux Framebuffer
  24 ~~~~~~~~~~~~~~~~~
  25
  26 [source,c]
  27 -------------------------------------------------------------------------------
  28 enum GP_LinuxFBFlags {
  29         GP_FB_INPUT_KBD = 0x01,
  30         GP_FB_SHADOW = 0x02,
  31         GP_FB_ALLOC_CON = 0x04,
  32 };
  33
  34 GP_Backend *GP_BackendLinuxFBInit(const char *path, int flags);
  35 -------------------------------------------------------------------------------
  36
  37 Initializes mmaped frame-buffer backend. The path is path to the frame-buffer
  38 device i.e. '/dev/fbX'.
  39
  40 If 'GP_FB_INPUT_KBD' flag is set console KBD driver is used to feed keystrokes
  41 into the event queue, otherwise no events are generated and you are expected to
  42 initialize input event driver yourself.
  43
  44 If 'GP_FB_SHADOW' flag is set shadow frame-buffer is allocated and used for
  45 drawing, the memory is blitted to mmaped frame-buffer on Blit() or UpdateRect()
  46 operation. Otherwise the frame-buffer mapped memory is used directly.
  47
  48 If 'GP_FB_ALLOC_CON' flag is set new console is allocated, otherwise current
  49 console is used.
  50
  51 SDL
  52 ~~~
  53
  54 [source,c]
  55 -------------------------------------------------------------------------------
  56 enum GP_BackendSDLFlags {
  57         GP_SDL_FULLSCREEN = 0x01,
  58         GP_SDL_RESIZABLE  = 0x02,
  59 };
  60
  61 GP_Backend *GP_BackendSDLInit(GP_Size w, GP_Size h,
  62                               uint8_t bpp, uint8_t flags,
  63                               const char *caption);
  64 -------------------------------------------------------------------------------
  65
  66 Initialize 'SDL' as a backend driver. The backend is thread safe as all the
  67 operations are guarded by locks.
  68
  69 You can't initialize more than one backend at a time, which is inherited 'SDL'
  70 limitation. If you call the initialization for a second time, you will get a
  71 pointer to already running backend.
  72
  73 If w, h and/or bpp are zero 'SDL' tries to do a guess, most of the time wrong
  74 for w and h though.
  75
  76 The caption is window caption.
  77
  78 And finally flags may change the 'SDL' to go to full-screen mode or make the
  79 window resizable.
  80
  81 [source,c]
  82 -------------------------------------------------------------------------------
  83 #include <backends/GP_SDL_Context.h>
  84
  85 int GP_ContextFromSDLSurface(GP_Context *c, const SDL_Surface *surf);
  86 -------------------------------------------------------------------------------
  87
  88 This function allows you to mix 'SDL' and 'GFXprim' code.
  89
  90 It initializes a 'GFXprim' context from the 'SDL' surface using the pixel
  91 buffer from surface as pixel buffer for the context.
  92
  93 Function returns zero on success and non-zero on failure (i.e. there is no
  94 'GFXprim' pixel type to match given surface).
  95
  96 For example usage see the link:example_SDL_glue.html[SDL glue example].
  97
  98 X Server
  99 ~~~~~~~~
 100
 101 [source,c]
 102 -------------------------------------------------------------------------------
 103 #include <GP.h>
 104 /* or */
 105 #include <backends/GP_X11.h>
 106
 107 enum GP_BackendX11Flags {
 108         /* When set, w and h is ignored and root window is used */
 109         GP_X11_USE_ROOT_WIN = 0x01,
 110
 111         /* Create new borderless window above the root window */
 112         GP_X11_CREATE_ROOT_WIN = 0x02,
 113
 114         /* Start fullscreen */
 115         GP_X11_FULLSCREEN = 0x04,
 116
 117         /* Do not use MIT SHM even if available */
 118         GP_X11_DISABLE_SHM = 0x08,
 119 };
 120
 121 GP_Backend *GP_BackendX11Init(const char *display, int x, int y,
 122                               unsigned int w, unsigned int h,
 123                               const char *caption,
 124                               enum GP_BackendX11Flags flags);
 125 -------------------------------------------------------------------------------
 126
 127 Returns pointer to initialized X11 backend or in case of failure 'NULL'.
 128
 129 When display is 'NULL' default display is used (which is what you want most of the
 130 time).
 131
 132 This backends supports multiple windows. Each time you call the initialization
 133 routine new backend structure is returned. All backend instances share the Xlib
 134 connection so you need to wait or poll only on one of them. Each backend, on
 135 the other hand, has its own input queue.
 136
 137 TIP: See multiple windows link:example_x11_windows.html[example].
 138
 139 GP_BackendIsX11
 140 ^^^^^^^^^^^^^^^
 141
 142 [source,c]
 143 -------------------------------------------------------------------------------
 144 #include <GP.h>
 145 /* or */
 146 #include <backends/GP_X11.h>
 147
 148 /*
 149  * Returns non-zero if backend is X11 backend
 150  */
 151 int GP_BackendIsX11(GP_Backend *self);
 152 -------------------------------------------------------------------------------
 153
 154 The 'GP_BackendIsX11()' returns non-zero if backend is X11 backend, zero
 155 otherwise.
 156
 157
 158 GP_BackendX11RequestFullscreen
 159 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 160
 161 [source,c]
 162 -------------------------------------------------------------------------------
 163 #include <GP.h>
 164 /* or */
 165 #include <backends/GP_X11.h>
 166
 167 /*
 168  * Changes full screen mode.
 169  *
 170  * 0 = off
 171  * 1 = on
 172  * 2 = toggle
 173  */
 174 void GP_BackendX11RequestFullscreen(GP_Backend *self, int mode);
 175 -------------------------------------------------------------------------------
 176
 177 The 'GP_BackendX11RequestFullscreen' can toggle fullscreen mode at runtime.
 178
 179 It will most likely generate resize event. See the 'GP_BackendResizeAck()' bellow.
 180
 181 AA-lib
 182 ~~~~~~
 183
 184 [source,c]
 185 -------------------------------------------------------------------------------
 186 #include <GP.h>
 187 /* or */
 188 #include <backends/AALib.h>
 189
 190 GP_Backend *GP_BackendAALibInit(void);
 191 -------------------------------------------------------------------------------
 192
 193 Currently the 'AA-lib' backend uses default initialization parameters.
 194
 195 Way how to pass 'AA-lib' specific parameters will be added. This interface
 196 will likely change.
 197
 198 [[Backend_Init]]
 199 Backend init function
 200 ~~~~~~~~~~~~~~~~~~~~~
 201
 202 Although there is no unified backend initialization, there is something close to
 203 it.
 204
 205 [source,c]
 206 -------------------------------------------------------------------------------
 207 #include <GP.h>
 208
 209 GP_Backend *GP_BackendInit(const char *params, const char *caption);
 210 -------------------------------------------------------------------------------
 211
 212 The 'params' string composes of backend name and backend dependend parameters.
 213 The format is 'backend_name:backend_params' for example
 214 'fb:new_console:/dev/fb1'.
 215
 216 The 'caption' string is used for window caption, in case of X11 backend or may
 217 be ignored completly in case of framebuffer backend.
 218
 219 If 'params' is set to '"help"' help for all backends is printed into the
 220 'stderr'.
 221
 222 If initialization was successful pointer to allocated and initialized backend
 223 is returned otherwise 'NULL' is returned and some helpful information should
 224 be printed into the 'stderr'.
 225
 226
 227 General Backend API
 228 ~~~~~~~~~~~~~~~~~~~
 229
 230 The backend API consist of a structure with callbacks. Every backend
 231 initialization yields this structure. Although is possible to call these
 232 pointers directly it's not recommended and everybody should rather use backend
 233 (inline) functions instead as they provide more convenient API and do
 234 additional sanity checks on parameters. Also functionality such as timers
 235 will not work if you decide to call raw callbacks.
 236
 237 [source,c]
 238 -------------------------------------------------------------------------------
 239 typdef struct GP_Backend {
 240         /*
 241          * Backend name.
 242          */
 243         const char *name;
 244
 245         /*
 246          * Pointer to context APP should draw to.
 247          */
 248         GP_Context *context;
 249
 250         ...
 251
 252         /*
 253          * Connection fd. Set to -1 if not available
 254          */
 255         int fd;
 256 };
 257 -------------------------------------------------------------------------------
 258
 259 The file descriptor 'fd' is either set to -1 (in case of 'SDL' or 'AA-lib' as
 260 they does not export it) or to a backend connection file descriptor usable for
 261 'select()' or 'poll()'.
 262
 263 GP_BackendExit
 264 ^^^^^^^^^^^^^^
 265
 266 [source,c]
 267 -------------------------------------------------------------------------------
 268 #include <backends/GP_Backend.h>
 269 /* or */
 270 #include <GP.h>
 271
 272 void GP_BackendExit(GP_Backend *backend);
 273 -------------------------------------------------------------------------------
 274
 275 Calls a backend exit callback. Restores the display, keyboard, etc. state
 276 back.
 277
 278 WARNING: It's important to call this functions on application exit. If you
 279          doesn't do so, the state of the display, resolution etc. may not be
 280          restored back to its original state. This includes program crashes and
 281          interruptions. Also this function may not be signal-async-safe, it's
 282          better to set signal handlers that calls it on SEGFAULT and SIGBUS
 283          as this usually works and not doing so may leave non-working system
 284          with black display or non-responding keyboard.
 285
 286
 287 GP_BackendFlip
 288 ^^^^^^^^^^^^^^
 289
 290 [source,c]
 291 -------------------------------------------------------------------------------
 292 #include <backends/GP_Backend.h>
 293 /* or */
 294 #include <GP.h>
 295
 296 GP_BackendFlip(GP_Backend *backend);
 297 -------------------------------------------------------------------------------
 298
 299 Flips a screen. Blits backend buffer to the screen or window if the backend is
 300 buffered.
 301
 302
 303 GP_BackendUpdateRect
 304 ^^^^^^^^^^^^^^^^^^^^
 305
 306 [source,c]
 307 -------------------------------------------------------------------------------
 308 #include <backends/GP_Backend.h>
 309 /* or */
 310 #include <GP.h>
 311
 312 void GP_BackendUpdateRect(GP_Backend *backend,
 313                           GP_Coord x0, GP_Coord y0,
 314                           GP_Coord x1, GP_Coord y1);
 315 -------------------------------------------------------------------------------
 316
 317 Updates particular rectangle in case backend is buffered.
 318
 319
 320 GP_BackendPoll
 321 ^^^^^^^^^^^^^^
 322
 323 [source,c]
 324 -------------------------------------------------------------------------------
 325 #include <backends/GP_Backend.h>
 326 /* or */
 327 #include <GP.h>
 328
 329 void GP_BackendPoll(GP_Backend *backend);
 330 -------------------------------------------------------------------------------
 331
 332 Polls for backend events.
 333
 334 The poll only reads events from event source (i.e. X11 socket, Linux evdev
 335 file descriptor), process them and may place new event into the backend event
 336 queue.
 337
 338 This call returns immediately after queued events (from X11 socket, etc.) were
 339 processed.
 340
 341 For backends that do not expose file descriptor (namely SDL) this should be
 342 called repeatedly. For other backends it may be called either repeatedly or
 343 when data are ready on file-descriptor.
 344
 345 If the backend is the only source of events in your application, you should
 346 consider using the 'GP_BackendWait()' or 'GP_BackendEventWait()' described
 347 bellow.
 348
 349 GP_BackendPollEvent
 350 ^^^^^^^^^^^^^^^^^^^
 351
 352 [source,c]
 353 -------------------------------------------------------------------------------
 354 #include <backends/GP_Backend.h>
 355 /* or */
 356 #include <GP.h>
 357
 358 int GP_BackendPollEvent(GP_Backend *self, GP_Event *ev);
 359 -------------------------------------------------------------------------------
 360
 361 Combines the 'GP_BackendPoll()' with 'GP_BackendGetEvent()'.
 362
 363 If there are any events in the backend event queue, the top event is removed
 364 from the queue and copied into the memory pointed by 'ev' and the call returns
 365 immediately.
 366
 367 If backend event queue is empty 'GP_BackendPoll()' is called. Then again the
 368 backend event queue is checked and if an event is found it's removed from the
 369 queue and copied into the 'ev'.
 370
 371 Returns non-zero if event was copied into the memory pointed by 'ev', zero
 372 otherwise.
 373
 374 .Example 'GP_BackendPollEvent()' usage.
 375 [source,c]
 376 -------------------------------------------------------------------------------
 377         /* Called either repeatedly or when data are ready on backend fd */
 378
 379         GP_Event ev;
 380
 381         while (GP_BackendPollEvent(backend, &ev) {
 382
 383                 /* process events */
 384
 385         }
 386 -------------------------------------------------------------------------------
 387
 388
 389 GP_BackendWait
 390 ^^^^^^^^^^^^^^
 391
 392 [source,c]
 393 -------------------------------------------------------------------------------
 394 #include <backends/GP_Backend.h>
 395 /* or */
 396 #include <GP.h>
 397
 398 void GP_BackendWait(GP_Backend *self);
 399 -------------------------------------------------------------------------------
 400
 401 Blocks until backend event arrives.
 402
 403 [NOTE]
 404 Events received by backend are not necessarily translated into the input
 405 events.
 406
 407 GP_BackendWaitEvent
 408 ^^^^^^^^^^^^^^^^^^^
 409
 410 [source,c]
 411 -------------------------------------------------------------------------------
 412 #include <backends/GP_Backend.h>
 413 /* or */
 414 #include <GP.h>
 415
 416 void GP_BackendWaitEvent(GP_Backend *self, GP_Event *ev);
 417 -------------------------------------------------------------------------------
 418
 419 Combines the 'GP_BackendWait()' with 'GP_BackendGetEvent()'.
 420
 421 If there are any events in the backend event queue, the top event is removed
 422 from the queue and copied into the memory pointed by 'ev' and the call returns
 423 immediately.
 424
 425 If backend event queue is empty 'GP_BackendWait()' is called until there are
 426 any events in the backend event queue. Then the top event is removed from the
 427 queue and the call returns.
 428
 429 .Example 'GP_BackendWaitEvent()' usage.
 430 [source,c]
 431 -------------------------------------------------------------------------------
 432         /* This is the main program loop */
 433         GP_Event ev;
 434
 435         for (;;) {
 436                 GP_BackendWaitEvent(backend, &ev);
 437
 438                 /* process events */
 439
 440         }
 441 -------------------------------------------------------------------------------
 442
 443 [[Timers]]
 444 GP_BackendAddTimer
 445 ^^^^^^^^^^^^^^^^^^
 446
 447 [source,c]
 448 -------------------------------------------------------------------------------
 449 #include <backends/GP_Backend.h>
 450 /* or */
 451 #include <GP.h>
 452
 453 void GP_BackendAddTimer(GP_Backend *self, GP_Timer *timer);
 454 -------------------------------------------------------------------------------
 455
 456 Adds a link:input.html#Timers[timer] to the backend timer queue.
 457
 458 Timers added to the backend are processed automatically while you call any of
 459 backend 'Poll' or 'Wait' functions.
 460
 461 If timer callback is set to 'NULL' a timer event is pushed to the backend
 462 input queue once timer has expired otherwise timer callback is called.
 463
 464 TIP: For example usage see backend timers
 465      link:example_backend_timers.html[example].
 466
 467 GP_BackendRemTimer
 468 ^^^^^^^^^^^^^^^^^^
 469
 470 [source,c]
 471 -------------------------------------------------------------------------------
 472 #include <backends/GP_Backend.h>
 473 /* or */
 474 #include <GP.h>
 475
 476 void GP_BackendRemTimer(GP_Backend *self, GP_Timer *timer);
 477 -------------------------------------------------------------------------------
 478
 479 Removes a link:input.html#Timers[timer] from the backend timer queue.
 480
 481 GP_BackendTimersInQueue
 482 ^^^^^^^^^^^^^^^^^^^^^^^
 483
 484 [source,c]
 485 -------------------------------------------------------------------------------
 486 #include <backends/GP_Backend.h>
 487 /* or */
 488 #include <GP.h>
 489
 490 void GP_BackendTimersInQueue(GP_Backend *self);
 491 -------------------------------------------------------------------------------
 492
 493 Returns number of timers scheduled in backend timer queue.
 494
 495 GP_BackendEventsQueued
 496 ^^^^^^^^^^^^^^^^^^^^^^
 497
 498 [source,c]
 499 -------------------------------------------------------------------------------
 500 #include <backends/GP_Backend.h>
 501 /* or */
 502 #include <GP.h>
 503
 504 unsigned int GP_BackendEventsQueued(GP_Backend *self);
 505 -------------------------------------------------------------------------------
 506
 507 Returns number of events queued in the backend event queue.
 508
 509
 510
 511 GP_BackendGetEvent
 512 ^^^^^^^^^^^^^^^^^^
 513
 514 [source,c]
 515 -------------------------------------------------------------------------------
 516 #include <backends/GP_Backend.h>
 517 /* or */
 518 #include <GP.h>
 519
 520 int GP_BackendGetEvent(GP_Backend *self, GP_Event *ev);
 521 -------------------------------------------------------------------------------
 522
 523 In case there are any events queued, the top event is removed from the queue,
 524 copied into the event structure that is passed as argument and non-zero is
 525 returned.
 526
 527 If there are no events queued the call returns immediately with zero return
 528 value.
 529
 530 TIP: For more information on events see link:input.html[input events]
 531      documentation.
 532
 533
 534 GP_BackendPeekEvent
 535 ^^^^^^^^^^^^^^^^^^^
 536
 537 [source,c]
 538 -------------------------------------------------------------------------------
 539 #include <backends/GP_Backend.h>
 540 /* or */
 541 #include <GP.h>
 542
 543 int GP_BackendPeekEvent(GP_Backend *self, GP_Event *ev);
 544 -------------------------------------------------------------------------------
 545
 546 Same as +GP_BackendPeekEvent()+ but the top event is not removed from the
 547 queue.
 548
 549 GP_BackendPutEventBack
 550 ^^^^^^^^^^^^^^^^^^^^^^
 551
 552 [source,c]
 553 -------------------------------------------------------------------------------
 554 #include <backends/GP_Backend.h>
 555 /* or */
 556 #include <GP.h>
 557
 558 void GP_BackendPutEventBack(GP_Backend *self, GP_Event *ev);
 559 -------------------------------------------------------------------------------
 560
 561 Puts event to the top of the queue. May be useful for putting back events that
 562 were removed from the queue.
 563
 564 GP_BackendSetCaption
 565 ^^^^^^^^^^^^^^^^^^^^
 566
 567 [source,c]
 568 -------------------------------------------------------------------------------
 569 #include <backends/GP_Backend.h>
 570 /* or */
 571 #include <GP.h>
 572
 573 int GP_BackendSetCaption(GP_Backend *backend, const char *caption)
 574 -------------------------------------------------------------------------------
 575
 576 Sets backend caption. On success zero is returned. On failure (backend doesn't
 577 support caption, operation failed) non zero is returned.
 578
 579
 580
 581 GP_BackendResize
 582 ^^^^^^^^^^^^^^^^
 583
 584 [source,c]
 585 -------------------------------------------------------------------------------
 586 #include <backends/GP_Backend.h>
 587 /* or */
 588 #include <GP.h>
 589
 590 int GP_BackendResize(GP_Backend *backend, uint32_t w, uint32_t h);
 591 -------------------------------------------------------------------------------
 592
 593 Requests backend resize. If backend resize is supported and the resize request
 594 was successful (i.e. X server allowed us to resize the window) the resize
 595 event will be send and should be handled in your event loop. You must respond
 596 to it by the 'GP_BackendResizeAck()' described bellow.
 597
 598 NOTE: The backend->context pointer may change upon calling this function and
 599       at least backend->context->pixels pointer will change.
 600
 601
 602 [[ResizeAck]]
 603 GP_BackendResizeAck
 604 ^^^^^^^^^^^^^^^^^^^
 605
 606 [source,c]
 607 -------------------------------------------------------------------------------
 608 #include <backends/GP_Backend.h>
 609 /* or */
 610 #include <GP.h>
 611
 612 int GP_BackendResizeAck(GP_Backend *self);
 613 -------------------------------------------------------------------------------
 614
 615 If backend is resizable by user interaction (for example X Window) you will
 616 get resize event for each change of window size, however the backend context
 617 will not be resized until you call this function. This is useful in
 618 multi-threaded application where one threads waits for events and others draws
 619 into the buffer so you can stop the drawing threads before the backend context
 620 size change.
 621
 622