1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2007,2008,2009,2011 Intel Corporation. 7 * Copyright (C) 2019 DisplayLink (UK) Ltd. 8 * 9 * Permission is hereby granted, free of charge, to any person 10 * obtaining a copy of this software and associated documentation 11 * files (the "Software"), to deal in the Software without 12 * restriction, including without limitation the rights to use, copy, 13 * modify, merge, publish, distribute, sublicense, and/or sell copies 14 * of the Software, and to permit persons to whom the Software is 15 * furnished to do so, subject to the following conditions: 16 * 17 * The above copyright notice and this permission notice shall be 18 * included in all copies or substantial portions of the Software. 19 * 20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 21 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 22 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 23 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 24 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 25 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 26 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 27 * SOFTWARE. 28 * 29 * 30 * 31 * Authors: 32 * Robert Bragg <robert@linux.intel.com> 33 */ 34 35 #ifndef __COGL_FRAMEBUFFER_H 36 #define __COGL_FRAMEBUFFER_H 37 38 39 #include <cogl/cogl-pipeline.h> 40 #include <cogl/cogl-indices.h> 41 #include <cogl/cogl-bitmap.h> 42 #include <cogl/cogl-texture.h> 43 #include <glib-object.h> 44 #include <cairo.h> 45 46 #include <graphene.h> 47 48 G_BEGIN_DECLS 49 50 /** 51 * SECTION:cogl-framebuffer 52 * @short_description: A common interface for manipulating framebuffers 53 * 54 * Framebuffers are a collection of buffers that can be rendered too. 55 * A framebuffer may be comprised of one or more color buffers, an 56 * optional depth buffer and an optional stencil buffer. Other 57 * configuration parameters are associated with framebuffers too such 58 * as whether the framebuffer supports multi-sampling (an anti-aliasing 59 * technique) or dithering. 60 * 61 * There are two kinds of framebuffer in Cogl, #CoglOnscreen 62 * framebuffers and #CoglOffscreen framebuffers. As the names imply 63 * offscreen framebuffers are for rendering something offscreen 64 * (perhaps to a texture which is bound as one of the color buffers). 65 * The exact semantics of onscreen framebuffers depends on the window 66 * system backend that you are using, but typically you can expect 67 * rendering to a #CoglOnscreen framebuffer will be immediately 68 * visible to the user. 69 * 70 * If you want to create a new framebuffer then you should start by 71 * looking at the #CoglOnscreen and #CoglOffscreen constructor 72 * functions, such as cogl_offscreen_new_with_texture() or 73 * cogl_onscreen_new(). The #CoglFramebuffer interface deals with 74 * all aspects that are common between those two types of framebuffer. 75 * 76 * Setup of a new CoglFramebuffer happens in two stages. There is a 77 * configuration stage where you specify all the options and ancillary 78 * buffers you want associated with your framebuffer and then when you 79 * are happy with the configuration you can "allocate" the framebuffer 80 * using cogl_framebuffer_allocate(). Technically explicitly calling 81 * cogl_framebuffer_allocate() is optional for convenience and the 82 * framebuffer will automatically be allocated when you first try to 83 * draw to it, but if you do the allocation manually then you can 84 * also catch any possible errors that may arise from your 85 * configuration. 86 */ 87 88 typedef struct _CoglFramebufferDriverConfig CoglFramebufferDriverConfig; 89 90 #define COGL_TYPE_FRAMEBUFFER (cogl_framebuffer_get_type ()) 91 COGL_EXPORT 92 G_DECLARE_DERIVABLE_TYPE (CoglFramebuffer, cogl_framebuffer, 93 COGL, FRAMEBUFFER, GObject) 94 95 struct _CoglFramebufferClass 96 { 97 /*< private >*/ 98 GObjectClass parent_class; 99 100 gboolean (* allocate) (CoglFramebuffer *framebuffer, 101 GError **error); 102 gboolean (* is_y_flipped) (CoglFramebuffer *framebuffer); 103 }; 104 105 /** 106 * cogl_framebuffer_allocate: 107 * @framebuffer: A #CoglFramebuffer 108 * @error: A pointer to a #GError for returning exceptions. 109 * 110 * Explicitly allocates a configured #CoglFramebuffer allowing developers to 111 * check and handle any errors that might arise from an unsupported 112 * configuration so that fallback configurations may be tried. 113 * 114 * <note>Many applications don't support any fallback options at least when 115 * they are initially developed and in that case the don't need to use this API 116 * since Cogl will automatically allocate a framebuffer when it first gets 117 * used. The disadvantage of relying on automatic allocation is that the 118 * program will abort with an error message if there is an error during 119 * automatic allocation.</note> 120 * 121 * Return value: %TRUE if there were no error allocating the framebuffer, else %FALSE. 122 * Since: 1.8 123 * Stability: unstable 124 */ 125 COGL_EXPORT gboolean 126 cogl_framebuffer_allocate (CoglFramebuffer *framebuffer, 127 GError **error); 128 129 /** 130 * cogl_framebuffer_get_width: 131 * @framebuffer: A #CoglFramebuffer 132 * 133 * Queries the current width of the given @framebuffer. 134 * 135 * Return value: The width of @framebuffer. 136 * Since: 1.8 137 * Stability: unstable 138 */ 139 COGL_EXPORT int 140 cogl_framebuffer_get_width (CoglFramebuffer *framebuffer); 141 142 /** 143 * cogl_framebuffer_get_height: 144 * @framebuffer: A #CoglFramebuffer 145 * 146 * Queries the current height of the given @framebuffer. 147 * 148 * Return value: The height of @framebuffer. 149 * Since: 1.8 150 * Stability: unstable 151 */ 152 COGL_EXPORT int 153 cogl_framebuffer_get_height (CoglFramebuffer *framebuffer); 154 155 /** 156 * cogl_framebuffer_set_viewport: 157 * @framebuffer: A #CoglFramebuffer 158 * @x: The top-left x coordinate of the viewport origin (only integers 159 * supported currently) 160 * @y: The top-left y coordinate of the viewport origin (only integers 161 * supported currently) 162 * @width: The width of the viewport (only integers supported currently) 163 * @height: The height of the viewport (only integers supported currently) 164 * 165 * Defines a scale and offset for everything rendered relative to the 166 * top-left of the destination framebuffer. 167 * 168 * By default the viewport has an origin of (0,0) and width and height 169 * that match the framebuffer's size. Assuming a default projection and 170 * modelview matrix then you could translate the contents of a window 171 * down and right by leaving the viewport size unchanged by moving the 172 * offset to (10,10). The viewport coordinates are measured in pixels. 173 * If you left the x and y origin as (0,0) you could scale the windows 174 * contents down by specify and width and height that's half the real 175 * size of the framebuffer. 176 * 177 * <note>Although the function takes floating point arguments, existing 178 * drivers only allow the use of integer values. In the future floating 179 * point values will be exposed via a checkable feature.</note> 180 * 181 * Since: 1.8 182 * Stability: unstable 183 */ 184 COGL_EXPORT void 185 cogl_framebuffer_set_viewport (CoglFramebuffer *framebuffer, 186 float x, 187 float y, 188 float width, 189 float height); 190 191 /** 192 * cogl_framebuffer_get_viewport_x: 193 * @framebuffer: A #CoglFramebuffer 194 * 195 * Queries the x coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() 196 * or the default value which is 0. 197 * 198 * Return value: The x coordinate of the viewport origin. 199 * Since: 1.8 200 * Stability: unstable 201 */ 202 COGL_EXPORT float 203 cogl_framebuffer_get_viewport_x (CoglFramebuffer *framebuffer); 204 205 /** 206 * cogl_framebuffer_get_viewport_y: 207 * @framebuffer: A #CoglFramebuffer 208 * 209 * Queries the y coordinate of the viewport origin as set using cogl_framebuffer_set_viewport() 210 * or the default value which is 0. 211 * 212 * Return value: The y coordinate of the viewport origin. 213 * Since: 1.8 214 * Stability: unstable 215 */ 216 COGL_EXPORT float 217 cogl_framebuffer_get_viewport_y (CoglFramebuffer *framebuffer); 218 219 /** 220 * cogl_framebuffer_get_viewport_width: 221 * @framebuffer: A #CoglFramebuffer 222 * 223 * Queries the width of the viewport as set using cogl_framebuffer_set_viewport() 224 * or the default value which is the width of the framebuffer. 225 * 226 * Return value: The width of the viewport. 227 * Since: 1.8 228 * Stability: unstable 229 */ 230 COGL_EXPORT float 231 cogl_framebuffer_get_viewport_width (CoglFramebuffer *framebuffer); 232 233 /** 234 * cogl_framebuffer_get_viewport_height: 235 * @framebuffer: A #CoglFramebuffer 236 * 237 * Queries the height of the viewport as set using cogl_framebuffer_set_viewport() 238 * or the default value which is the height of the framebuffer. 239 * 240 * Return value: The height of the viewport. 241 * Since: 1.8 242 * Stability: unstable 243 */ 244 COGL_EXPORT float 245 cogl_framebuffer_get_viewport_height (CoglFramebuffer *framebuffer); 246 247 /** 248 * cogl_framebuffer_get_viewport4fv: 249 * @framebuffer: A #CoglFramebuffer 250 * @viewport: (out caller-allocates) (array fixed-size=4): A pointer to an 251 * array of 4 floats to receive the (x, y, width, height) 252 * components of the current viewport. 253 * 254 * Queries the x, y, width and height components of the current viewport as set 255 * using cogl_framebuffer_set_viewport() or the default values which are 0, 0, 256 * framebuffer_width and framebuffer_height. The values are written into the 257 * given @viewport array. 258 * 259 * Since: 1.8 260 * Stability: unstable 261 */ 262 COGL_EXPORT void 263 cogl_framebuffer_get_viewport4fv (CoglFramebuffer *framebuffer, 264 float *viewport); 265 266 /** 267 * cogl_framebuffer_push_matrix: 268 * @framebuffer: A #CoglFramebuffer pointer 269 * 270 * Copies the current model-view matrix onto the matrix stack. The matrix 271 * can later be restored with cogl_framebuffer_pop_matrix(). 272 * 273 * Since: 1.10 274 */ 275 COGL_EXPORT void 276 cogl_framebuffer_push_matrix (CoglFramebuffer *framebuffer); 277 278 /** 279 * cogl_framebuffer_pop_matrix: 280 * @framebuffer: A #CoglFramebuffer pointer 281 * 282 * Restores the model-view matrix on the top of the matrix stack. 283 * 284 * Since: 1.10 285 */ 286 COGL_EXPORT void 287 cogl_framebuffer_pop_matrix (CoglFramebuffer *framebuffer); 288 289 /** 290 * cogl_framebuffer_identity_matrix: 291 * @framebuffer: A #CoglFramebuffer pointer 292 * 293 * Resets the current model-view matrix to the identity matrix. 294 * 295 * Since: 1.10 296 * Stability: unstable 297 */ 298 COGL_EXPORT void 299 cogl_framebuffer_identity_matrix (CoglFramebuffer *framebuffer); 300 301 /** 302 * cogl_framebuffer_scale: 303 * @framebuffer: A #CoglFramebuffer pointer 304 * @x: Amount to scale along the x-axis 305 * @y: Amount to scale along the y-axis 306 * @z: Amount to scale along the z-axis 307 * 308 * Multiplies the current model-view matrix by one that scales the x, 309 * y and z axes by the given values. 310 * 311 * Since: 1.10 312 * Stability: unstable 313 */ 314 COGL_EXPORT void 315 cogl_framebuffer_scale (CoglFramebuffer *framebuffer, 316 float x, 317 float y, 318 float z); 319 320 /** 321 * cogl_framebuffer_translate: 322 * @framebuffer: A #CoglFramebuffer pointer 323 * @x: Distance to translate along the x-axis 324 * @y: Distance to translate along the y-axis 325 * @z: Distance to translate along the z-axis 326 * 327 * Multiplies the current model-view matrix by one that translates the 328 * model along all three axes according to the given values. 329 * 330 * Since: 1.10 331 * Stability: unstable 332 */ 333 COGL_EXPORT void 334 cogl_framebuffer_translate (CoglFramebuffer *framebuffer, 335 float x, 336 float y, 337 float z); 338 339 /** 340 * cogl_framebuffer_rotate: 341 * @framebuffer: A #CoglFramebuffer pointer 342 * @angle: Angle in degrees to rotate. 343 * @x: X-component of vertex to rotate around. 344 * @y: Y-component of vertex to rotate around. 345 * @z: Z-component of vertex to rotate around. 346 * 347 * Multiplies the current model-view matrix by one that rotates the 348 * model around the axis-vector specified by @x, @y and @z. The 349 * rotation follows the right-hand thumb rule so for example rotating 350 * by 10 degrees about the axis-vector (0, 0, 1) causes a small 351 * counter-clockwise rotation. 352 * 353 * Since: 1.10 354 * Stability: unstable 355 */ 356 COGL_EXPORT void 357 cogl_framebuffer_rotate (CoglFramebuffer *framebuffer, 358 float angle, 359 float x, 360 float y, 361 float z); 362 363 /** 364 * cogl_framebuffer_rotate_euler: 365 * @framebuffer: A #CoglFramebuffer pointer 366 * @euler: A #graphene_euler_t 367 * 368 * Multiplies the current model-view matrix by one that rotates 369 * according to the rotation described by @euler. 370 * 371 * Since: 2.0 372 * Stability: unstable 373 */ 374 COGL_EXPORT void 375 cogl_framebuffer_rotate_euler (CoglFramebuffer *framebuffer, 376 const graphene_euler_t *euler); 377 378 /** 379 * cogl_framebuffer_transform: 380 * @framebuffer: A #CoglFramebuffer pointer 381 * @matrix: the matrix to multiply with the current model-view 382 * 383 * Multiplies the current model-view matrix by the given matrix. 384 * 385 * Since: 1.10 386 * Stability: unstable 387 */ 388 COGL_EXPORT void 389 cogl_framebuffer_transform (CoglFramebuffer *framebuffer, 390 const graphene_matrix_t *matrix); 391 392 /** 393 * cogl_framebuffer_get_modelview_matrix: 394 * @framebuffer: A #CoglFramebuffer pointer 395 * @matrix: (out): return location for the model-view matrix 396 * 397 * Stores the current model-view matrix in @matrix. 398 * 399 * Since: 1.10 400 * Stability: unstable 401 */ 402 COGL_EXPORT void 403 cogl_framebuffer_get_modelview_matrix (CoglFramebuffer *framebuffer, 404 graphene_matrix_t *matrix); 405 406 /** 407 * cogl_framebuffer_set_modelview_matrix: 408 * @framebuffer: A #CoglFramebuffer pointer 409 * @matrix: the new model-view matrix 410 * 411 * Sets @matrix as the new model-view matrix. 412 * 413 * Since: 1.10 414 * Stability: unstable 415 */ 416 COGL_EXPORT void 417 cogl_framebuffer_set_modelview_matrix (CoglFramebuffer *framebuffer, 418 const graphene_matrix_t *matrix); 419 420 /** 421 * cogl_framebuffer_perspective: 422 * @framebuffer: A #CoglFramebuffer pointer 423 * @fov_y: Vertical field of view angle in degrees. 424 * @aspect: The (width over height) aspect ratio for display 425 * @z_near: The distance to the near clipping plane (Must be positive, 426 * and must not be 0) 427 * @z_far: The distance to the far clipping plane (Must be positive) 428 * 429 * Replaces the current projection matrix with a perspective matrix 430 * based on the provided values. 431 * 432 * <note>You should be careful not to have to great a @z_far / @z_near 433 * ratio since that will reduce the effectiveness of depth testing 434 * since there won't be enough precision to identify the depth of 435 * objects near to each other.</note> 436 * 437 * Since: 1.10 438 * Stability: unstable 439 */ 440 COGL_EXPORT void 441 cogl_framebuffer_perspective (CoglFramebuffer *framebuffer, 442 float fov_y, 443 float aspect, 444 float z_near, 445 float z_far); 446 447 /** 448 * cogl_framebuffer_frustum: 449 * @framebuffer: A #CoglFramebuffer pointer 450 * @left: X position of the left clipping plane where it 451 * intersects the near clipping plane 452 * @right: X position of the right clipping plane where it 453 * intersects the near clipping plane 454 * @bottom: Y position of the bottom clipping plane where it 455 * intersects the near clipping plane 456 * @top: Y position of the top clipping plane where it intersects 457 * the near clipping plane 458 * @z_near: The distance to the near clipping plane (Must be positive) 459 * @z_far: The distance to the far clipping plane (Must be positive) 460 * 461 * Replaces the current projection matrix with a perspective matrix 462 * for a given viewing frustum defined by 4 side clip planes that 463 * all cross through the origin and 2 near and far clip planes. 464 * 465 * Since: 1.10 466 * Stability: unstable 467 */ 468 COGL_EXPORT void 469 cogl_framebuffer_frustum (CoglFramebuffer *framebuffer, 470 float left, 471 float right, 472 float bottom, 473 float top, 474 float z_near, 475 float z_far); 476 477 /** 478 * cogl_framebuffer_orthographic: 479 * @framebuffer: A #CoglFramebuffer pointer 480 * @x_1: The x coordinate for the first vertical clipping plane 481 * @y_1: The y coordinate for the first horizontal clipping plane 482 * @x_2: The x coordinate for the second vertical clipping plane 483 * @y_2: The y coordinate for the second horizontal clipping plane 484 * @near: The <emphasis>distance</emphasis> to the near clipping 485 * plane (will be <emphasis>negative</emphasis> if the plane is 486 * behind the viewer) 487 * @far: The <emphasis>distance</emphasis> to the far clipping 488 * plane (will be <emphasis>negative</emphasis> if the plane is 489 * behind the viewer) 490 * 491 * Replaces the current projection matrix with an orthographic projection 492 * matrix. 493 * 494 * Since: 1.10 495 * Stability: unstable 496 */ 497 COGL_EXPORT void 498 cogl_framebuffer_orthographic (CoglFramebuffer *framebuffer, 499 float x_1, 500 float y_1, 501 float x_2, 502 float y_2, 503 float near, 504 float far); 505 506 /** 507 * cogl_framebuffer_get_projection_matrix: 508 * @framebuffer: A #CoglFramebuffer pointer 509 * @matrix: (out): return location for the projection matrix 510 * 511 * Stores the current projection matrix in @matrix. 512 * 513 * Since: 1.10 514 * Stability: unstable 515 */ 516 COGL_EXPORT void 517 cogl_framebuffer_get_projection_matrix (CoglFramebuffer *framebuffer, 518 graphene_matrix_t *matrix); 519 520 /** 521 * cogl_framebuffer_set_projection_matrix: 522 * @framebuffer: A #CoglFramebuffer pointer 523 * @matrix: the new projection matrix 524 * 525 * Sets @matrix as the new projection matrix. 526 * 527 * Since: 1.10 528 * Stability: unstable 529 */ 530 COGL_EXPORT void 531 cogl_framebuffer_set_projection_matrix (CoglFramebuffer *framebuffer, 532 const graphene_matrix_t *matrix); 533 534 /** 535 * cogl_framebuffer_push_scissor_clip: 536 * @framebuffer: A #CoglFramebuffer pointer 537 * @x: left edge of the clip rectangle in window coordinates 538 * @y: top edge of the clip rectangle in window coordinates 539 * @width: width of the clip rectangle 540 * @height: height of the clip rectangle 541 * 542 * Specifies a rectangular clipping area for all subsequent drawing 543 * operations. Any drawing commands that extend outside the rectangle 544 * will be clipped so that only the portion inside the rectangle will 545 * be displayed. The rectangle dimensions are not transformed by the 546 * current model-view matrix. 547 * 548 * The rectangle is intersected with the current clip region. To undo 549 * the effect of this function, call cogl_framebuffer_pop_clip(). 550 * 551 * Since: 1.10 552 * Stability: unstable 553 */ 554 COGL_EXPORT void 555 cogl_framebuffer_push_scissor_clip (CoglFramebuffer *framebuffer, 556 int x, 557 int y, 558 int width, 559 int height); 560 561 /** 562 * cogl_framebuffer_push_rectangle_clip: 563 * @framebuffer: A #CoglFramebuffer pointer 564 * @x_1: x coordinate for top left corner of the clip rectangle 565 * @y_1: y coordinate for top left corner of the clip rectangle 566 * @x_2: x coordinate for bottom right corner of the clip rectangle 567 * @y_2: y coordinate for bottom right corner of the clip rectangle 568 * 569 * Specifies a modelview transformed rectangular clipping area for all 570 * subsequent drawing operations. Any drawing commands that extend 571 * outside the rectangle will be clipped so that only the portion 572 * inside the rectangle will be displayed. The rectangle dimensions 573 * are transformed by the current model-view matrix. 574 * 575 * The rectangle is intersected with the current clip region. To undo 576 * the effect of this function, call cogl_framebuffer_pop_clip(). 577 * 578 * Since: 1.10 579 * Stability: unstable 580 */ 581 COGL_EXPORT void 582 cogl_framebuffer_push_rectangle_clip (CoglFramebuffer *framebuffer, 583 float x_1, 584 float y_1, 585 float x_2, 586 float y_2); 587 588 /** 589 * cogl_framebuffer_push_primitive_clip: (skip) 590 * @framebuffer: A #CoglFramebuffer pointer 591 * @primitive: A #CoglPrimitive describing a flat 2D shape 592 * @bounds_x1: x coordinate for the top-left corner of the primitives 593 * bounds 594 * @bounds_y1: y coordinate for the top-left corner of the primitives 595 * bounds 596 * @bounds_x2: x coordinate for the bottom-right corner of the 597 * primitives bounds. 598 * @bounds_y2: y coordinate for the bottom-right corner of the 599 * primitives bounds. 600 * 601 * Sets a new clipping area using a 2D shaped described with a 602 * #CoglPrimitive. The shape must not contain self overlapping 603 * geometry and must lie on a single 2D plane. A bounding box of the 604 * 2D shape in local coordinates (the same coordinates used to 605 * describe the shape) must be given. It is acceptable for the bounds 606 * to be larger than the true bounds but behaviour is undefined if the 607 * bounds are smaller than the true bounds. 608 * 609 * The primitive is transformed by the current model-view matrix and 610 * the silhouette is intersected with the previous clipping area. To 611 * restore the previous clipping area, call 612 * cogl_framebuffer_pop_clip(). 613 * 614 * Since: 1.10 615 * Stability: unstable 616 */ 617 COGL_EXPORT void 618 cogl_framebuffer_push_primitive_clip (CoglFramebuffer *framebuffer, 619 CoglPrimitive *primitive, 620 float bounds_x1, 621 float bounds_y1, 622 float bounds_x2, 623 float bounds_y2); 624 625 COGL_EXPORT void 626 cogl_framebuffer_push_region_clip (CoglFramebuffer *framebuffer, 627 cairo_region_t *region); 628 629 /** 630 * cogl_framebuffer_pop_clip: 631 * @framebuffer: A #CoglFramebuffer pointer 632 * 633 * Reverts the clipping region to the state before the last call to 634 * cogl_framebuffer_push_scissor_clip(), cogl_framebuffer_push_rectangle_clip() 635 * cogl_framebuffer_push_path_clip(), or cogl_framebuffer_push_primitive_clip(). 636 * 637 * Since: 1.10 638 * Stability: unstable 639 */ 640 COGL_EXPORT void 641 cogl_framebuffer_pop_clip (CoglFramebuffer *framebuffer); 642 643 /** 644 * cogl_framebuffer_get_red_bits: 645 * @framebuffer: a pointer to a #CoglFramebuffer 646 * 647 * Retrieves the number of red bits of @framebuffer 648 * 649 * Return value: the number of bits 650 * 651 * Since: 1.8 652 * Stability: unstable 653 */ 654 COGL_EXPORT int 655 cogl_framebuffer_get_red_bits (CoglFramebuffer *framebuffer); 656 657 /** 658 * cogl_framebuffer_get_green_bits: 659 * @framebuffer: a pointer to a #CoglFramebuffer 660 * 661 * Retrieves the number of green bits of @framebuffer 662 * 663 * Return value: the number of bits 664 * 665 * Since: 1.8 666 * Stability: unstable 667 */ 668 COGL_EXPORT int 669 cogl_framebuffer_get_green_bits (CoglFramebuffer *framebuffer); 670 671 /** 672 * cogl_framebuffer_get_blue_bits: 673 * @framebuffer: a pointer to a #CoglFramebuffer 674 * 675 * Retrieves the number of blue bits of @framebuffer 676 * 677 * Return value: the number of bits 678 * 679 * Since: 1.8 680 * Stability: unstable 681 */ 682 COGL_EXPORT int 683 cogl_framebuffer_get_blue_bits (CoglFramebuffer *framebuffer); 684 685 /** 686 * cogl_framebuffer_get_alpha_bits: 687 * @framebuffer: a pointer to a #CoglFramebuffer 688 * 689 * Retrieves the number of alpha bits of @framebuffer 690 * 691 * Return value: the number of bits 692 * 693 * Since: 1.8 694 * Stability: unstable 695 */ 696 COGL_EXPORT int 697 cogl_framebuffer_get_alpha_bits (CoglFramebuffer *framebuffer); 698 699 /** 700 * cogl_framebuffer_get_depth_bits: 701 * @framebuffer: a pointer to a #CoglFramebuffer 702 * 703 * Retrieves the number of depth bits of @framebuffer 704 * 705 * Return value: the number of bits 706 * 707 * Since: 2.0 708 * Stability: unstable 709 */ 710 COGL_EXPORT int 711 cogl_framebuffer_get_depth_bits (CoglFramebuffer *framebuffer); 712 713 /* 714 * cogl_framebuffer_get_is_stereo: 715 * @framebuffer: a pointer to a #CoglFramebuffer 716 * 717 * Retrieves whether @framebuffer has separate left and right 718 * buffers for use with stereo drawing. See 719 * cogl_framebuffer_set_stereo_mode(). 720 * 721 * Return value: %TRUE if @framebuffer has separate left and 722 * right buffers. 723 * 724 * Since: 1.20 725 * Stability: unstable 726 */ 727 COGL_EXPORT gboolean 728 cogl_framebuffer_get_is_stereo (CoglFramebuffer *framebuffer); 729 730 /** 731 * cogl_framebuffer_get_dither_enabled: 732 * @framebuffer: a pointer to a #CoglFramebuffer 733 * 734 * Returns whether dithering has been requested for the given @framebuffer. 735 * See cogl_framebuffer_set_dither_enabled() for more details about dithering. 736 * 737 * <note>This may return %TRUE even when the underlying @framebuffer 738 * display pipeline does not support dithering. This value only represents 739 * the user's request for dithering.</note> 740 * 741 * Return value: %TRUE if dithering has been requested or %FALSE if not. 742 * Since: 1.8 743 * Stability: unstable 744 */ 745 COGL_EXPORT gboolean 746 cogl_framebuffer_get_dither_enabled (CoglFramebuffer *framebuffer); 747 748 /** 749 * cogl_framebuffer_set_dither_enabled: 750 * @framebuffer: a pointer to a #CoglFramebuffer 751 * @dither_enabled: %TRUE to enable dithering or %FALSE to disable 752 * 753 * Enables or disabled dithering if supported by the hardware. 754 * 755 * Dithering is a hardware dependent technique to increase the visible 756 * color resolution beyond what the underlying hardware supports by playing 757 * tricks with the colors placed into the framebuffer to give the illusion 758 * of other colors. (For example this can be compared to half-toning used 759 * by some news papers to show varying levels of grey even though their may 760 * only be black and white are available). 761 * 762 * If the current display pipeline for @framebuffer does not support dithering 763 * then this has no affect. 764 * 765 * Dithering is enabled by default. 766 * 767 * Since: 1.8 768 * Stability: unstable 769 */ 770 COGL_EXPORT void 771 cogl_framebuffer_set_dither_enabled (CoglFramebuffer *framebuffer, 772 gboolean dither_enabled); 773 774 /** 775 * cogl_framebuffer_get_depth_write_enabled: 776 * @framebuffer: a pointer to a #CoglFramebuffer 777 * 778 * Queries whether depth buffer writing is enabled for @framebuffer. This 779 * can be controlled via cogl_framebuffer_set_depth_write_enabled(). 780 * 781 * Return value: %TRUE if depth writing is enabled or %FALSE if not. 782 * Since: 1.18 783 * Stability: unstable 784 */ 785 COGL_EXPORT gboolean 786 cogl_framebuffer_get_depth_write_enabled (CoglFramebuffer *framebuffer); 787 788 /** 789 * cogl_framebuffer_set_depth_write_enabled: 790 * @framebuffer: a pointer to a #CoglFramebuffer 791 * @depth_write_enabled: %TRUE to enable depth writing or %FALSE to disable 792 * 793 * Enables or disables depth buffer writing when rendering to @framebuffer. 794 * If depth writing is enabled for both the framebuffer and the rendering 795 * pipeline, and the framebuffer has an associated depth buffer, depth 796 * information will be written to this buffer during rendering. 797 * 798 * Depth buffer writing is enabled by default. 799 * 800 * Since: 1.18 801 * Stability: unstable 802 */ 803 COGL_EXPORT void 804 cogl_framebuffer_set_depth_write_enabled (CoglFramebuffer *framebuffer, 805 gboolean depth_write_enabled); 806 807 /** 808 * cogl_framebuffer_get_stereo_mode: 809 * @framebuffer: a pointer to a #CoglFramebuffer 810 * 811 * Gets the current #CoglStereoMode, which defines which stereo buffers 812 * should be drawn to. See cogl_framebuffer_set_stereo_mode(). 813 * 814 * Returns: A #CoglStereoMode 815 * Since: 1.20 816 * Stability: unstable 817 */ 818 COGL_EXPORT CoglStereoMode 819 cogl_framebuffer_get_stereo_mode (CoglFramebuffer *framebuffer); 820 821 /** 822 * cogl_framebuffer_set_stereo_mode: 823 * @framebuffer: a pointer to a #CoglFramebuffer 824 * @stereo_mode: A #CoglStereoMode specifying which stereo buffers 825 * should be drawn tow. 826 * 827 * Sets which stereo buffers should be drawn to. The default 828 * is %COGL_STEREO_BOTH, which means that both the left and 829 * right buffers will be affected by drawing. For this to have 830 * an effect, the display system must support stereo drawables, 831 * and the framebuffer must have been created with stereo 832 * enabled. (See cogl_onscreen_template_set_stereo_enabled(), 833 * cogl_framebuffer_get_is_stereo().) 834 * 835 * Since: 1.20 836 * Stability: unstable 837 */ 838 COGL_EXPORT void 839 cogl_framebuffer_set_stereo_mode (CoglFramebuffer *framebuffer, 840 CoglStereoMode stereo_mode); 841 842 /** 843 * cogl_framebuffer_set_samples_per_pixel: 844 * @framebuffer: A #CoglFramebuffer framebuffer 845 * @samples_per_pixel: The minimum number of samples per pixel 846 * 847 * Requires that when rendering to @framebuffer then @n point samples 848 * should be made per pixel which will all contribute to the final 849 * resolved color for that pixel. The idea is that the hardware aims 850 * to get quality similar to what you would get if you rendered 851 * everything twice as big (for 4 samples per pixel) and then scaled 852 * that image back down with filtering. It can effectively remove the 853 * jagged edges of polygons and should be more efficient than if you 854 * were to manually render at a higher resolution and downscale 855 * because the hardware is often able to take some shortcuts. For 856 * example the GPU may only calculate a single texture sample for all 857 * points of a single pixel, and for tile based architectures all the 858 * extra sample data (such as depth and stencil samples) may be 859 * handled on-chip and so avoid increased demand on system memory 860 * bandwidth. 861 * 862 * By default this value is usually set to 0 and that is referred to 863 * as "single-sample" rendering. A value of 1 or greater is referred 864 * to as "multisample" rendering. 865 * 866 * <note>There are some semantic differences between single-sample 867 * rendering and multisampling with just 1 point sample such as it 868 * being redundant to use the cogl_framebuffer_resolve_samples() and 869 * cogl_framebuffer_resolve_samples_region() apis with single-sample 870 * rendering.</note> 871 * 872 * <note>It's recommended that 873 * cogl_framebuffer_resolve_samples_region() be explicitly used at the 874 * end of rendering to a point sample buffer to minimize the number of 875 * samples that get resolved. By default Cogl will implicitly resolve 876 * all framebuffer samples but if only a small region of a 877 * framebuffer has changed this can lead to redundant work being 878 * done.</note> 879 * 880 * Since: 1.8 881 * Stability: unstable 882 */ 883 COGL_EXPORT void 884 cogl_framebuffer_set_samples_per_pixel (CoglFramebuffer *framebuffer, 885 int samples_per_pixel); 886 887 /** 888 * cogl_framebuffer_get_samples_per_pixel: 889 * @framebuffer: A #CoglFramebuffer framebuffer 890 * 891 * Gets the number of points that are sampled per-pixel when 892 * rasterizing geometry. Usually by default this will return 0 which 893 * means that single-sample not multisample rendering has been chosen. 894 * When using a GPU supporting multisample rendering it's possible to 895 * increase the number of samples per pixel using 896 * cogl_framebuffer_set_samples_per_pixel(). 897 * 898 * Calling cogl_framebuffer_get_samples_per_pixel() before the 899 * framebuffer has been allocated will simply return the value set 900 * using cogl_framebuffer_set_samples_per_pixel(). After the 901 * framebuffer has been allocated the value will reflect the actual 902 * number of samples that will be made by the GPU. 903 * 904 * Returns: The number of point samples made per pixel when 905 * rasterizing geometry or 0 if single-sample rendering 906 * has been chosen. 907 * 908 * Since: 1.10 909 * Stability: unstable 910 */ 911 COGL_EXPORT int 912 cogl_framebuffer_get_samples_per_pixel (CoglFramebuffer *framebuffer); 913 914 915 /** 916 * cogl_framebuffer_resolve_samples: 917 * @framebuffer: A #CoglFramebuffer framebuffer 918 * 919 * When point sample rendering (also known as multisample rendering) 920 * has been enabled via cogl_framebuffer_set_samples_per_pixel() 921 * then you can optionally call this function (or 922 * cogl_framebuffer_resolve_samples_region()) to explicitly resolve 923 * the point samples into values for the final color buffer. 924 * 925 * Some GPUs will implicitly resolve the point samples during 926 * rendering and so this function is effectively a nop, but with other 927 * architectures it is desirable to defer the resolve step until the 928 * end of the frame. 929 * 930 * Since Cogl will automatically ensure samples are resolved if the 931 * target color buffer is used as a source this API only needs to be 932 * used if explicit control is desired - perhaps because you want to 933 * ensure that the resolve is completed in advance to avoid later 934 * having to wait for the resolve to complete. 935 * 936 * If you are performing incremental updates to a framebuffer you 937 * should consider using cogl_framebuffer_resolve_samples_region() 938 * instead to avoid resolving redundant pixels. 939 * 940 * Since: 1.8 941 * Stability: unstable 942 */ 943 COGL_EXPORT void 944 cogl_framebuffer_resolve_samples (CoglFramebuffer *framebuffer); 945 946 /** 947 * cogl_framebuffer_resolve_samples_region: 948 * @framebuffer: A #CoglFramebuffer framebuffer 949 * @x: top-left x coordinate of region to resolve 950 * @y: top-left y coordinate of region to resolve 951 * @width: width of region to resolve 952 * @height: height of region to resolve 953 * 954 * When point sample rendering (also known as multisample rendering) 955 * has been enabled via cogl_framebuffer_set_samples_per_pixel() 956 * then you can optionally call this function (or 957 * cogl_framebuffer_resolve_samples()) to explicitly resolve the point 958 * samples into values for the final color buffer. 959 * 960 * Some GPUs will implicitly resolve the point samples during 961 * rendering and so this function is effectively a nop, but with other 962 * architectures it is desirable to defer the resolve step until the 963 * end of the frame. 964 * 965 * Use of this API is recommended if incremental, small updates to 966 * a framebuffer are being made because by default Cogl will 967 * implicitly resolve all the point samples of the framebuffer which 968 * can result in redundant work if only a small number of samples have 969 * changed. 970 * 971 * Because some GPUs implicitly resolve point samples this function 972 * only guarantees that at-least the region specified will be resolved 973 * and if you have rendered to a larger region then it's possible that 974 * other samples may be implicitly resolved. 975 * 976 * Since: 1.8 977 * Stability: unstable 978 */ 979 COGL_EXPORT void 980 cogl_framebuffer_resolve_samples_region (CoglFramebuffer *framebuffer, 981 int x, 982 int y, 983 int width, 984 int height); 985 986 /** 987 * cogl_framebuffer_get_context: 988 * @framebuffer: A #CoglFramebuffer 989 * 990 * Can be used to query the #CoglContext a given @framebuffer was 991 * instantiated within. This is the #CoglContext that was passed to 992 * cogl_onscreen_new() for example. 993 * 994 * Return value: (transfer none): The #CoglContext that the given 995 * @framebuffer was instantiated within. 996 * Since: 1.8 997 * Stability: unstable 998 */ 999 COGL_EXPORT CoglContext * 1000 cogl_framebuffer_get_context (CoglFramebuffer *framebuffer); 1001 1002 /** 1003 * cogl_framebuffer_clear: 1004 * @framebuffer: A #CoglFramebuffer 1005 * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary 1006 * buffers to clear 1007 * @color: The color to clear the color buffer too if specified in 1008 * @buffers. 1009 * 1010 * Clears all the auxiliary buffers identified in the @buffers mask, and if 1011 * that includes the color buffer then the specified @color is used. 1012 * 1013 * Since: 1.8 1014 * Stability: unstable 1015 */ 1016 COGL_EXPORT void 1017 cogl_framebuffer_clear (CoglFramebuffer *framebuffer, 1018 unsigned long buffers, 1019 const CoglColor *color); 1020 1021 /** 1022 * cogl_framebuffer_clear4f: 1023 * @framebuffer: A #CoglFramebuffer 1024 * @buffers: A mask of #CoglBufferBit<!-- -->'s identifying which auxiliary 1025 * buffers to clear 1026 * @red: The red component of color to clear the color buffer too if 1027 * specified in @buffers. 1028 * @green: The green component of color to clear the color buffer too if 1029 * specified in @buffers. 1030 * @blue: The blue component of color to clear the color buffer too if 1031 * specified in @buffers. 1032 * @alpha: The alpha component of color to clear the color buffer too if 1033 * specified in @buffers. 1034 * 1035 * Clears all the auxiliary buffers identified in the @buffers mask, and if 1036 * that includes the color buffer then the specified @color is used. 1037 * 1038 * Since: 1.8 1039 * Stability: unstable 1040 */ 1041 COGL_EXPORT void 1042 cogl_framebuffer_clear4f (CoglFramebuffer *framebuffer, 1043 unsigned long buffers, 1044 float red, 1045 float green, 1046 float blue, 1047 float alpha); 1048 1049 /** 1050 * cogl_framebuffer_draw_primitive: (skip) 1051 * @framebuffer: A destination #CoglFramebuffer 1052 * @pipeline: A #CoglPipeline state object 1053 * @primitive: A #CoglPrimitive geometry object 1054 * 1055 * Draws the given @primitive geometry to the specified destination 1056 * @framebuffer using the graphics processing state described by @pipeline. 1057 * 1058 * This drawing api doesn't support high-level meta texture types such 1059 * as #CoglTexture2DSliced so it is the user's responsibility to 1060 * ensure that only low-level textures that can be directly sampled by 1061 * a GPU such as #CoglTexture2D are associated with layers of the given 1062 * @pipeline. 1063 * 1064 * <note>This api doesn't support any of the legacy global state options such 1065 * as cogl_set_depth_test_enabled() or 1066 * cogl_set_backface_culling_enabled().</note> 1067 * 1068 * Stability: unstable 1069 * Since: 1.10 1070 * Deprecated: 1.16: Use #CoglPrimitive<!-- -->s and 1071 * cogl_primitive_draw() instead 1072 */ 1073 COGL_DEPRECATED_FOR (cogl_primitive_draw) 1074 COGL_EXPORT void 1075 cogl_framebuffer_draw_primitive (CoglFramebuffer *framebuffer, 1076 CoglPipeline *pipeline, 1077 CoglPrimitive *primitive); 1078 1079 /** 1080 * cogl_framebuffer_draw_rectangle: 1081 * @framebuffer: A destination #CoglFramebuffer 1082 * @pipeline: A #CoglPipeline state object 1083 * @x_1: X coordinate of the top-left corner 1084 * @y_1: Y coordinate of the top-left corner 1085 * @x_2: X coordinate of the bottom-right corner 1086 * @y_2: Y coordinate of the bottom-right corner 1087 * 1088 * Draws a rectangle to @framebuffer with the given @pipeline state 1089 * and with the top left corner positioned at (@x_1, @y_1) and the 1090 * bottom right corner positioned at (@x_2, @y_2). 1091 * 1092 * <note>The position is the position before the rectangle has been 1093 * transformed by the model-view matrix and the projection 1094 * matrix.</note> 1095 * 1096 * <note>If you want to describe a rectangle with a texture mapped on 1097 * it then you can use 1098 * cogl_framebuffer_draw_textured_rectangle().</note> 1099 * 1100 * Since: 1.10 1101 * Stability: unstable 1102 */ 1103 COGL_EXPORT void 1104 cogl_framebuffer_draw_rectangle (CoglFramebuffer *framebuffer, 1105 CoglPipeline *pipeline, 1106 float x_1, 1107 float y_1, 1108 float x_2, 1109 float y_2); 1110 1111 /** 1112 * cogl_framebuffer_draw_textured_rectangle: 1113 * @framebuffer: A destination #CoglFramebuffer 1114 * @pipeline: A #CoglPipeline state object 1115 * @x_1: x coordinate upper left on screen. 1116 * @y_1: y coordinate upper left on screen. 1117 * @x_2: x coordinate lower right on screen. 1118 * @y_2: y coordinate lower right on screen. 1119 * @s_1: S texture coordinate of the top-left coorner 1120 * @t_1: T texture coordinate of the top-left coorner 1121 * @s_2: S texture coordinate of the bottom-right coorner 1122 * @t_2: T texture coordinate of the bottom-right coorner 1123 * 1124 * Draws a textured rectangle to @framebuffer using the given 1125 * @pipeline state with the top left corner positioned at (@x_1, @y_1) 1126 * and the bottom right corner positioned at (@x_2, @y_2). The top 1127 * left corner will have texture coordinates of (@s_1, @t_1) and the 1128 * bottom right corner will have texture coordinates of (@s_2, @t_2). 1129 * 1130 * <note>The position is the position before the rectangle has been 1131 * transformed by the model-view matrix and the projection 1132 * matrix.</note> 1133 * 1134 * This is a high level drawing api that can handle any kind of 1135 * #CoglMetaTexture texture such as #CoglTexture2DSliced textures 1136 * which may internally be comprised of multiple low-level textures. 1137 * This is unlike low-level drawing apis such as cogl_primitive_draw() 1138 * which only support low level texture types that are directly 1139 * supported by GPUs such as #CoglTexture2D. 1140 * 1141 * <note>The given texture coordinates will only be used for the first 1142 * texture layer of the pipeline and if your pipeline has more than 1143 * one layer then all other layers will have default texture 1144 * coordinates of @s_1=0.0 @t_1=0.0 @s_2=1.0 @t_2=1.0 </note> 1145 * 1146 * The given texture coordinates should always be normalized such that 1147 * (0, 0) corresponds to the top left and (1, 1) corresponds to the 1148 * bottom right. To map an entire texture across the rectangle pass 1149 * in @s_1=0, @t_1=0, @s_2=1, @t_2=1. 1150 * 1151 * Since: 1.10 1152 * Stability: unstable 1153 */ 1154 COGL_EXPORT void 1155 cogl_framebuffer_draw_textured_rectangle (CoglFramebuffer *framebuffer, 1156 CoglPipeline *pipeline, 1157 float x_1, 1158 float y_1, 1159 float x_2, 1160 float y_2, 1161 float s_1, 1162 float t_1, 1163 float s_2, 1164 float t_2); 1165 1166 /** 1167 * cogl_framebuffer_draw_multitextured_rectangle: 1168 * @framebuffer: A destination #CoglFramebuffer 1169 * @pipeline: A #CoglPipeline state object 1170 * @x_1: x coordinate upper left on screen. 1171 * @y_1: y coordinate upper left on screen. 1172 * @x_2: x coordinate lower right on screen. 1173 * @y_2: y coordinate lower right on screen. 1174 * @tex_coords: (in) (array) (transfer none): An array containing groups of 1175 * 4 float values: [s_1, t_1, s_2, t_2] that are interpreted as two texture 1176 * coordinates; one for the top left texel, and one for the bottom right 1177 * texel. Each value should be between 0.0 and 1.0, where the coordinate 1178 * (0.0, 0.0) represents the top left of the texture, and (1.0, 1.0) the 1179 * bottom right. 1180 * @tex_coords_len: The length of the @tex_coords array. (For one layer 1181 * and one group of texture coordinates, this would be 4) 1182 * 1183 * Draws a textured rectangle to @framebuffer with the given @pipeline 1184 * state with the top left corner positioned at (@x_1, @y_1) and the 1185 * bottom right corner positioned at (@x_2, @y_2). As a pipeline may 1186 * contain multiple texture layers this interface lets you supply 1187 * texture coordinates for each layer of the pipeline. 1188 * 1189 * <note>The position is the position before the rectangle has been 1190 * transformed by the model-view matrix and the projection 1191 * matrix.</note> 1192 * 1193 * This is a high level drawing api that can handle any kind of 1194 * #CoglMetaTexture texture for the first layer such as 1195 * #CoglTexture2DSliced textures which may internally be comprised of 1196 * multiple low-level textures. This is unlike low-level drawing apis 1197 * such as cogl_primitive_draw() which only support low level texture 1198 * types that are directly supported by GPUs such as #CoglTexture2D. 1199 * 1200 * <note>This api can not currently handle multiple high-level meta 1201 * texture layers. The first layer may be a high level meta texture 1202 * such as #CoglTexture2DSliced but all other layers much be low 1203 * level textures such as #CoglTexture2D. 1204 * 1205 * The top left texture coordinate for layer 0 of any pipeline will be 1206 * (tex_coords[0], tex_coords[1]) and the bottom right coordinate will 1207 * be (tex_coords[2], tex_coords[3]). The coordinates for layer 1 1208 * would be (tex_coords[4], tex_coords[5]) (tex_coords[6], 1209 * tex_coords[7]) and so on... 1210 * 1211 * The given texture coordinates should always be normalized such that 1212 * (0, 0) corresponds to the top left and (1, 1) corresponds to the 1213 * bottom right. To map an entire texture across the rectangle pass 1214 * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, 1215 * tex_coords[3]=1. 1216 * 1217 * The first pair of coordinates are for the first layer (with the 1218 * smallest layer index) and if you supply less texture coordinates 1219 * than there are layers in the current source material then default 1220 * texture coordinates (0.0, 0.0, 1.0, 1.0) are generated. 1221 * 1222 * Since: 1.10 1223 * Stability: unstable 1224 */ 1225 COGL_EXPORT void 1226 cogl_framebuffer_draw_multitextured_rectangle (CoglFramebuffer *framebuffer, 1227 CoglPipeline *pipeline, 1228 float x_1, 1229 float y_1, 1230 float x_2, 1231 float y_2, 1232 const float *tex_coords, 1233 int tex_coords_len); 1234 1235 /** 1236 * cogl_framebuffer_draw_rectangles: 1237 * @framebuffer: A destination #CoglFramebuffer 1238 * @pipeline: A #CoglPipeline state object 1239 * @coordinates: (in) (array) (transfer none): an array of coordinates 1240 * containing groups of 4 float values: [x_1, y_1, x_2, y_2] that are 1241 * interpreted as two position coordinates; one for the top left of 1242 * the rectangle (x1, y1), and one for the bottom right of the 1243 * rectangle (x2, y2). 1244 * @n_rectangles: number of rectangles defined in @coordinates. 1245 * 1246 * Draws a series of rectangles to @framebuffer with the given 1247 * @pipeline state in the same way that 1248 * cogl_framebuffer_draw_rectangle() does. 1249 * 1250 * The top left corner of the first rectangle is positioned at 1251 * (coordinates[0], coordinates[1]) and the bottom right corner is 1252 * positioned at (coordinates[2], coordinates[3]). The positions for 1253 * the second rectangle are (coordinates[4], coordinates[5]) and 1254 * (coordinates[6], coordinates[7]) and so on... 1255 * 1256 * <note>The position is the position before the rectangle has been 1257 * transformed by the model-view matrix and the projection 1258 * matrix.</note> 1259 * 1260 * As a general rule for better performance its recommended to use 1261 * this this API instead of calling 1262 * cogl_framebuffer_draw_textured_rectangle() separately for multiple 1263 * rectangles if all of the rectangles will be drawn together with the 1264 * same @pipeline state. 1265 * 1266 * Since: 1.10 1267 * Stability: unstable 1268 */ 1269 COGL_EXPORT void 1270 cogl_framebuffer_draw_rectangles (CoglFramebuffer *framebuffer, 1271 CoglPipeline *pipeline, 1272 const float *coordinates, 1273 unsigned int n_rectangles); 1274 1275 /** 1276 * cogl_framebuffer_draw_textured_rectangles: 1277 * @framebuffer: A destination #CoglFramebuffer 1278 * @pipeline: A #CoglPipeline state object 1279 * @coordinates: (in) (array) (transfer none): an array containing 1280 * groups of 8 float values: [x_1, y_1, x_2, y_2, s_1, t_1, s_2, t_2] 1281 * that have the same meaning as the arguments for 1282 * cogl_framebuffer_draw_textured_rectangle(). 1283 * @n_rectangles: number of rectangles to @coordinates to draw 1284 * 1285 * Draws a series of rectangles to @framebuffer with the given 1286 * @pipeline state in the same way that 1287 * cogl_framebuffer_draw_textured_rectangle() does. 1288 * 1289 * <note>The position is the position before the rectangle has been 1290 * transformed by the model-view matrix and the projection 1291 * matrix.</note> 1292 * 1293 * This is a high level drawing api that can handle any kind of 1294 * #CoglMetaTexture texture such as #CoglTexture2DSliced textures 1295 * which may internally be comprised of multiple low-level textures. 1296 * This is unlike low-level drawing apis such as cogl_primitive_draw() 1297 * which only support low level texture types that are directly 1298 * supported by GPUs such as #CoglTexture2D. 1299 * 1300 * The top left corner of the first rectangle is positioned at 1301 * (coordinates[0], coordinates[1]) and the bottom right corner is 1302 * positioned at (coordinates[2], coordinates[3]). The top left 1303 * texture coordinate is (coordinates[4], coordinates[5]) and the 1304 * bottom right texture coordinate is (coordinates[6], 1305 * coordinates[7]). The coordinates for subsequent rectangles 1306 * are defined similarly by the subsequent coordinates. 1307 * 1308 * As a general rule for better performance its recommended to use 1309 * this this API instead of calling 1310 * cogl_framebuffer_draw_textured_rectangle() separately for multiple 1311 * rectangles if all of the rectangles will be drawn together with the 1312 * same @pipeline state. 1313 * 1314 * The given texture coordinates should always be normalized such that 1315 * (0, 0) corresponds to the top left and (1, 1) corresponds to the 1316 * bottom right. To map an entire texture across the rectangle pass 1317 * in tex_coords[0]=0, tex_coords[1]=0, tex_coords[2]=1, 1318 * tex_coords[3]=1. 1319 * 1320 * Since: 1.10 1321 * Stability: unstable 1322 */ 1323 COGL_EXPORT void 1324 cogl_framebuffer_draw_textured_rectangles (CoglFramebuffer *framebuffer, 1325 CoglPipeline *pipeline, 1326 const float *coordinates, 1327 unsigned int n_rectangles); 1328 1329 /* XXX: Should we take an n_buffers + buffer id array instead of using 1330 * the CoglBufferBits type which doesn't seem future proof? */ 1331 /** 1332 * cogl_framebuffer_discard_buffers: 1333 * @framebuffer: A #CoglFramebuffer 1334 * @buffers: A #CoglBufferBit mask of which ancillary buffers you want 1335 * to discard. 1336 * 1337 * Declares that the specified @buffers no longer need to be referenced 1338 * by any further rendering commands. This can be an important 1339 * optimization to avoid subsequent frames of rendering depending on 1340 * the results of a previous frame. 1341 * 1342 * For example; some tile-based rendering GPUs are able to avoid allocating and 1343 * accessing system memory for the depth and stencil buffer so long as these 1344 * buffers are not required as input for subsequent frames and that can save a 1345 * significant amount of memory bandwidth used to save and restore their 1346 * contents to system memory between frames. 1347 * 1348 * It is currently considered an error to try and explicitly discard the color 1349 * buffer by passing %COGL_BUFFER_BIT_COLOR. This is because the color buffer is 1350 * already implicitly discard when you finish rendering to a #CoglOnscreen 1351 * framebuffer, and it's not meaningful to try and discard the color buffer of 1352 * a #CoglOffscreen framebuffer since they are single-buffered. 1353 * 1354 * 1355 * Since: 1.8 1356 * Stability: unstable 1357 */ 1358 COGL_EXPORT void 1359 cogl_framebuffer_discard_buffers (CoglFramebuffer *framebuffer, 1360 unsigned long buffers); 1361 1362 /** 1363 * cogl_framebuffer_finish: 1364 * @framebuffer: A #CoglFramebuffer pointer 1365 * 1366 * This blocks the CPU until all pending rendering associated with the 1367 * specified framebuffer has completed. It's very rare that developers should 1368 * ever need this level of synchronization with the GPU and should never be 1369 * used unless you clearly understand why you need to explicitly force 1370 * synchronization. 1371 * 1372 * One example might be for benchmarking purposes to be sure timing 1373 * measurements reflect the time that the GPU is busy for not just the time it 1374 * takes to queue rendering commands. 1375 * 1376 * Stability: unstable 1377 * Since: 1.10 1378 */ 1379 COGL_EXPORT void 1380 cogl_framebuffer_finish (CoglFramebuffer *framebuffer); 1381 1382 /** 1383 * cogl_framebuffer_read_pixels_into_bitmap: 1384 * @framebuffer: A #CoglFramebuffer 1385 * @x: The x position to read from 1386 * @y: The y position to read from 1387 * @source: Identifies which auxiliary buffer you want to read 1388 * (only COGL_READ_PIXELS_COLOR_BUFFER supported currently) 1389 * @bitmap: The bitmap to store the results in. 1390 * 1391 * This reads a rectangle of pixels from the given framebuffer where 1392 * position (0, 0) is the top left. The pixel at (x, y) is the first 1393 * read, and a rectangle of pixels with the same size as the bitmap is 1394 * read right and downwards from that point. 1395 * 1396 * Currently Cogl assumes that the framebuffer is in a premultiplied 1397 * format so if the format of @bitmap is non-premultiplied it will 1398 * convert it. To read the pixel values without any conversion you 1399 * should either specify a format that doesn't use an alpha channel or 1400 * use one of the formats ending in PRE. 1401 * 1402 * Return value: %TRUE if the read succeeded or %FALSE otherwise. The 1403 * function is only likely to fail if the bitmap points to a pixel 1404 * buffer and it could not be mapped. 1405 * Since: 1.10 1406 * Stability: unstable 1407 */ 1408 COGL_EXPORT gboolean 1409 cogl_framebuffer_read_pixels_into_bitmap (CoglFramebuffer *framebuffer, 1410 int x, 1411 int y, 1412 CoglReadPixelsFlags source, 1413 CoglBitmap *bitmap); 1414 1415 /** 1416 * cogl_framebuffer_read_pixels: 1417 * @framebuffer: A #CoglFramebuffer 1418 * @x: The x position to read from 1419 * @y: The y position to read from 1420 * @width: The width of the region of rectangles to read 1421 * @height: The height of the region of rectangles to read 1422 * @format: The pixel format to store the data in 1423 * @pixels: The address of the buffer to store the data in 1424 * 1425 * This is a convenience wrapper around 1426 * cogl_framebuffer_read_pixels_into_bitmap() which allocates a 1427 * temporary #CoglBitmap to read pixel data directly into the given 1428 * buffer. The rowstride of the buffer is assumed to be the width of 1429 * the region times the bytes per pixel of the format. The source for 1430 * the data is always taken from the color buffer. If you want to use 1431 * any other rowstride or source, please use the 1432 * cogl_framebuffer_read_pixels_into_bitmap() function directly. 1433 * 1434 * The implementation of the function looks like this: 1435 * 1436 * |[ 1437 * bitmap = cogl_bitmap_new_for_data (context, 1438 * width, height, 1439 * format, 1440 * /<!-- -->* rowstride *<!-- -->/ 1441 * bpp * width, 1442 * pixels); 1443 * cogl_framebuffer_read_pixels_into_bitmap (framebuffer, 1444 * x, y, 1445 * COGL_READ_PIXELS_COLOR_BUFFER, 1446 * bitmap); 1447 * cogl_object_unref (bitmap); 1448 * ]| 1449 * 1450 * Return value: %TRUE if the read succeeded or %FALSE otherwise. 1451 * Since: 1.10 1452 * Stability: unstable 1453 */ 1454 COGL_EXPORT gboolean 1455 cogl_framebuffer_read_pixels (CoglFramebuffer *framebuffer, 1456 int x, 1457 int y, 1458 int width, 1459 int height, 1460 CoglPixelFormat format, 1461 uint8_t *pixels); 1462 1463 COGL_EXPORT uint32_t 1464 cogl_framebuffer_error_quark (void); 1465 1466 /** 1467 * COGL_FRAMEBUFFER_ERROR: 1468 * 1469 * An error domain for reporting #CoglFramebuffer exceptions 1470 */ 1471 #define COGL_FRAMEBUFFER_ERROR (cogl_framebuffer_error_quark ()) 1472 1473 typedef enum /*< prefix=COGL_FRAMEBUFFER_ERROR >*/ 1474 { 1475 COGL_FRAMEBUFFER_ERROR_ALLOCATE 1476 } CoglFramebufferError; 1477 1478 /** 1479 * cogl_is_framebuffer: 1480 * @object: A #CoglObject pointer 1481 * 1482 * Gets whether the given object references a #CoglFramebuffer. 1483 * 1484 * Return value: %TRUE if the object references a #CoglFramebuffer 1485 * and %FALSE otherwise. 1486 * Since: 1.10 1487 * Stability: unstable 1488 */ 1489 COGL_EXPORT gboolean 1490 cogl_is_framebuffer (void *object); 1491 1492 /** 1493 * cogl_blit_framebuffer: 1494 * @framebuffer: The source #CoglFramebuffer 1495 * @dst: The destination #CoglFramebuffer 1496 * @src_x: Source x position 1497 * @src_y: Source y position 1498 * @dst_x: Destination x position 1499 * @dst_y: Destination y position 1500 * @width: Width of region to copy 1501 * @height: Height of region to copy 1502 * @error: optional error object 1503 * 1504 * @return FALSE for an immediately detected error, TRUE otherwise. 1505 * 1506 * This blits a region of the color buffer of the source buffer 1507 * to the destination buffer. This function should only be 1508 * called if the COGL_FEATURE_ID_BLIT_FRAMEBUFFER feature is 1509 * advertised. 1510 * 1511 * The source and destination rectangles are defined in offscreen 1512 * framebuffer orientation. When copying between an offscreen and 1513 * onscreen framebuffers, the image is y-flipped accordingly. 1514 * 1515 * The two buffers must have the same value types (e.g. floating-point, 1516 * unsigned int, signed int, or fixed-point), but color formats do not 1517 * need to match. This limitation comes from OpenGL ES 3.0 definition 1518 * of glBlitFramebuffer. 1519 * 1520 * Note that this function differs a lot from the glBlitFramebuffer 1521 * function provided by the GL_EXT_framebuffer_blit extension. Notably 1522 * it doesn't support having different sizes for the source and 1523 * destination rectangle. This doesn't seem 1524 * like a particularly useful feature. If the application wanted to 1525 * scale the results it may make more sense to draw a primitive 1526 * instead. 1527 * 1528 * The GL function is documented to be affected by the scissor. This 1529 * function therefore ensure that an empty clip stack is flushed 1530 * before performing the blit which means the scissor is effectively 1531 * ignored. 1532 * 1533 * The function also doesn't support specifying the buffers to copy 1534 * and instead only the color buffer is copied. When copying the depth 1535 * or stencil buffers the extension on GLES2.0 only supports copying 1536 * the full buffer which would be awkward to document with this 1537 * API. If we wanted to support that feature it may be better to have 1538 * a separate function to copy the entire buffer for a given mask. 1539 * 1540 * The @c error argument is optional, it can be NULL. If it is not NULL 1541 * and this function returns FALSE, an error object with a code from 1542 * COGL_SYSTEM_ERROR will be created. 1543 */ 1544 COGL_EXPORT gboolean 1545 cogl_blit_framebuffer (CoglFramebuffer *framebuffer, 1546 CoglFramebuffer *dst, 1547 int src_x, 1548 int src_y, 1549 int dst_x, 1550 int dst_y, 1551 int width, 1552 int height, 1553 GError **error); 1554 1555 /** 1556 * cogl_framebuffer_flush: 1557 * @framebuffer: A #CoglFramebuffer pointer 1558 * 1559 * Flushes @framebuffer to ensure the current batch of commands is 1560 * submitted to the GPU. 1561 * 1562 * Unlike cogl_framebuffer_finish(), this does not block the CPU. 1563 */ 1564 COGL_EXPORT void 1565 cogl_framebuffer_flush (CoglFramebuffer *framebuffer); 1566 1567 /** 1568 * cogl_framebuffer_create_timestamp_query: (skip) 1569 * 1570 * Creates a query for the GPU timestamp that will complete upon completion of 1571 * all previously submitted GL commands related to this framebuffer. E.g. when 1572 * the rendering is finished on this framebuffer. 1573 * 1574 * This function should only be called if the COGL_FEATURE_ID_TIMESTAMP_QUERY 1575 * feature is advertised. 1576 */ 1577 COGL_EXPORT CoglTimestampQuery * 1578 cogl_framebuffer_create_timestamp_query (CoglFramebuffer *framebuffer); 1579 1580 G_END_DECLS 1581 1582 #endif /* __COGL_FRAMEBUFFER_H */ 1583