1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2007,2008,2009,2012 Intel Corporation. 7 * 8 * Permission is hereby granted, free of charge, to any person 9 * obtaining a copy of this software and associated documentation 10 * files (the "Software"), to deal in the Software without 11 * restriction, including without limitation the rights to use, copy, 12 * modify, merge, publish, distribute, sublicense, and/or sell copies 13 * of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be 17 * included in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 20 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 22 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 23 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 24 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 25 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 26 * SOFTWARE. 27 * 28 * 29 */ 30 31 #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) 32 #error "Only <cogl/cogl.h> can be included directly." 33 #endif 34 35 #ifndef __COGL_OFFSCREEN_H__ 36 #define __COGL_OFFSCREEN_H__ 37 38 #include <cogl/cogl-types.h> 39 #include <cogl/cogl-texture.h> 40 41 #ifdef COGL_HAS_GTYPE_SUPPORT 42 #include <glib-object.h> 43 #endif 44 45 COGL_BEGIN_DECLS 46 47 /** 48 * SECTION:cogl-offscreen 49 * @short_description: Functions for creating and manipulating offscreen 50 * framebuffers. 51 * 52 * Cogl allows creating and operating on offscreen framebuffers. 53 */ 54 55 typedef struct _CoglOffscreen CoglOffscreen; 56 57 #define COGL_OFFSCREEN(X) ((CoglOffscreen *)X) 58 59 #ifdef COGL_HAS_GTYPE_SUPPORT 60 /** 61 * cogl_offscreen_get_gtype: 62 * 63 * Returns: a #GType that can be used with the GLib type system. 64 */ 65 GType cogl_offscreen_get_gtype (void); 66 #endif 67 68 /* Offscreen api */ 69 70 /** 71 * cogl_offscreen_new_with_texture: 72 * @texture: A #CoglTexture pointer 73 * 74 * This creates an offscreen framebuffer object using the given 75 * @texture as the primary color buffer. It doesn't just initialize 76 * the contents of the offscreen buffer with the @texture; they are 77 * tightly bound so that drawing to the offscreen buffer effectively 78 * updates the contents of the given texture. You don't need to 79 * destroy the offscreen buffer before you can use the @texture again. 80 * 81 * <note>This api only works with low-level #CoglTexture types such as 82 * #CoglTexture2D, #CoglTexture3D and #CoglTextureRectangle, and not 83 * with meta-texture types such as #CoglTexture2DSliced.</note> 84 * 85 * The storage for the framebuffer is actually allocated lazily 86 * so this function will never return %NULL to indicate a runtime 87 * error. This means it is still possible to configure the framebuffer 88 * before it is really allocated. 89 * 90 * Simple applications without full error handling can simply rely on 91 * Cogl to lazily allocate the storage of framebuffers but you should 92 * be aware that if Cogl encounters an error (such as running out of 93 * GPU memory) then your application will simply abort with an error 94 * message. If you need to be able to catch such exceptions at runtime 95 * then you can explicitly allocate your framebuffer when you have 96 * finished configuring it by calling cogl_framebuffer_allocate() and 97 * passing in a #CoglError argument to catch any exceptions. 98 * 99 * Return value: (transfer full): a newly instantiated #CoglOffscreen 100 * framebuffer. 101 */ 102 CoglOffscreen * 103 cogl_offscreen_new_with_texture (CoglTexture *texture); 104 105 /** 106 * cogl_offscreen_new_to_texture: 107 * @texture: A #CoglTexture pointer 108 * 109 * This creates an offscreen buffer object using the given @texture as the 110 * primary color buffer. It doesn't just initialize the contents of the 111 * offscreen buffer with the @texture; they are tightly bound so that 112 * drawing to the offscreen buffer effectivly updates the contents of the 113 * given texture. You don't need to destroy the offscreen buffer before 114 * you can use the @texture again. 115 * 116 * <note>This only works with low-level #CoglTexture types such as 117 * #CoglTexture2D, #CoglTexture3D and #CoglTextureRectangle, and not 118 * with meta-texture types such as #CoglTexture2DSliced.</note> 119 * 120 * Return value: (transfer full): a newly instantiated #CoglOffscreen 121 * framebuffer or %NULL if it wasn't possible to create the 122 * buffer. 123 * Deprecated: 1.16: Use cogl_offscreen_new_with_texture instead. 124 */ 125 COGL_DEPRECATED_IN_1_16_FOR (cogl_offscreen_new_with_texture) 126 CoglOffscreen * 127 cogl_offscreen_new_to_texture (CoglTexture *texture); 128 129 /** 130 * cogl_is_offscreen: 131 * @object: A pointer to a #CoglObject 132 * 133 * Determines whether the given #CoglObject references an offscreen 134 * framebuffer object. 135 * 136 * Returns: %TRUE if @object is a #CoglOffscreen framebuffer, 137 * %FALSE otherwise 138 */ 139 CoglBool 140 cogl_is_offscreen (void *object); 141 142 /** 143 * cogl_offscreen_ref: 144 * @offscreen: A pointer to a #CoglOffscreen framebuffer 145 * 146 * Increments the reference count on the @offscreen framebuffer. 147 * 148 * Return value: (transfer none): For convenience it returns the 149 * given @offscreen 150 * 151 * Deprecated: 1.2: cogl_object_ref() should be used in new code. 152 */ 153 COGL_DEPRECATED_FOR (cogl_object_ref) 154 void * 155 cogl_offscreen_ref (void *offscreen); 156 157 /** 158 * cogl_offscreen_unref: 159 * @offscreen: A pointer to a #CoglOffscreen framebuffer 160 * 161 * Decreases the reference count for the @offscreen buffer and frees it when 162 * the count reaches 0. 163 * 164 * Deprecated: 1.2: cogl_object_unref() should be used in new code. 165 */ 166 COGL_DEPRECATED_FOR (cogl_object_unref) 167 void 168 cogl_offscreen_unref (void *offscreen); 169 170 COGL_END_DECLS 171 172 #endif /* __COGL_OFFSCREEN_H__ */ 173