1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2010 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 * Authors: 29 * Robert Bragg <robert@linux.intel.com> 30 * 31 */ 32 33 #if !defined(__COGL_H_INSIDE__) && !defined(COGL_COMPILATION) 34 #error "Only <cogl/cogl.h> can be included directly." 35 #endif 36 37 #ifndef __COGL_CONTEXT_H__ 38 #define __COGL_CONTEXT_H__ 39 40 /* We forward declare the CoglContext type here to avoid some circular 41 * dependency issues with the following headers. 42 */ 43 typedef struct _CoglContext CoglContext; 44 typedef struct _CoglTimestampQuery CoglTimestampQuery; 45 46 #include <cogl/cogl-defines.h> 47 #include <cogl/cogl-display.h> 48 #include <cogl/cogl-pipeline.h> 49 #include <cogl/cogl-primitive.h> 50 51 #include <glib-object.h> 52 53 G_BEGIN_DECLS 54 55 /** 56 * SECTION:cogl-context 57 * @short_description: The top level application context. 58 * 59 * A #CoglContext is the top most sandbox of Cogl state for an 60 * application or toolkit. Its main purpose is to act as a sandbox 61 * for the memory management of state objects. Normally an application 62 * will only create a single context since there is no way to share 63 * resources between contexts. 64 * 65 * For those familiar with OpenGL or perhaps Cairo it should be 66 * understood that unlike these APIs a Cogl context isn't a rendering 67 * context as such. In other words Cogl doesn't aim to provide a state 68 * machine style model for configuring rendering parameters. Most 69 * rendering state in Cogl is directly associated with user managed 70 * objects called pipelines and geometry is drawn with a specific 71 * pipeline object to a framebuffer object and those 3 things fully 72 * define the state for drawing. This is an important part of Cogl's 73 * design since it helps you write orthogonal rendering components 74 * that can all access the same GPU without having to worry about 75 * what state other components have left you with. 76 * 77 * <note><para>Cogl does not maintain internal references to the context for 78 * resources that depend on the context so applications. This is to 79 * help applications control the lifetime a context without us needing to 80 * introduce special api to handle the breakup of internal circular 81 * references due to internal resources and caches associated with the 82 * context. 83 * 84 * One a context has been destroyed then all directly or indirectly 85 * dependent resources will be in an inconsistent state and should not 86 * be manipulated or queried in any way. 87 * 88 * For applications that rely on the operating system to clean up 89 * resources this policy shouldn't affect them, but for applications 90 * that need to carefully destroy and re-create Cogl contexts multiple 91 * times throughout their lifetime (such as Android applications) they 92 * should be careful to destroy all context dependent resources, such as 93 * framebuffers or textures etc before unrefing and destroying the 94 * context.</para></note> 95 */ 96 97 #define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT) 98 99 /** 100 * cogl_context_get_gtype: 101 * 102 * Returns: a #GType that can be used with the GLib type system. 103 */ 104 COGL_EXPORT 105 GType cogl_context_get_gtype (void); 106 107 /** 108 * cogl_context_new: (constructor) (skip) 109 * @display: (allow-none): A #CoglDisplay pointer 110 * @error: A GError return location. 111 * 112 * Creates a new #CoglContext which acts as an application sandbox 113 * for any state objects that are allocated. 114 * 115 * Return value: (transfer full): A newly allocated #CoglContext 116 * Since: 1.8 117 * Stability: unstable 118 */ 119 COGL_EXPORT CoglContext * 120 cogl_context_new (CoglDisplay *display, 121 GError **error); 122 123 /** 124 * cogl_context_get_display: (skip) 125 * @context: A #CoglContext pointer 126 * 127 * Retrieves the #CoglDisplay that is internally associated with the 128 * given @context. This will return the same #CoglDisplay that was 129 * passed to cogl_context_new() or if %NULL was passed to 130 * cogl_context_new() then this function returns a pointer to the 131 * display that was automatically setup internally. 132 * 133 * Return value: (transfer none): The #CoglDisplay associated with the 134 * given @context. 135 * Since: 1.8 136 * Stability: unstable 137 */ 138 COGL_EXPORT CoglDisplay * 139 cogl_context_get_display (CoglContext *context); 140 141 /** 142 * cogl_context_get_renderer: (skip) 143 * @context: A #CoglContext pointer 144 * 145 * Retrieves the #CoglRenderer that is internally associated with the 146 * given @context. This will return the same #CoglRenderer that was 147 * passed to cogl_display_new() or if %NULL was passed to 148 * cogl_display_new() or cogl_context_new() then this function returns 149 * a pointer to the renderer that was automatically connected 150 * internally. 151 * 152 * Return value: (transfer none): The #CoglRenderer associated with the 153 * given @context. 154 * Since: 1.16 155 * Stability: unstable 156 */ 157 COGL_EXPORT CoglRenderer * 158 cogl_context_get_renderer (CoglContext *context); 159 160 /** 161 * cogl_is_context: 162 * @object: An object or %NULL 163 * 164 * Gets whether the given object references an existing context object. 165 * 166 * Return value: %TRUE if the @object references a #CoglContext, 167 * %FALSE otherwise 168 * 169 * Since: 1.10 170 * Stability: Unstable 171 */ 172 COGL_EXPORT gboolean 173 cogl_is_context (void *object); 174 175 /* XXX: not guarded by the EXPERIMENTAL_API defines to avoid 176 * upsetting glib-mkenums, but this can still be considered implicitly 177 * experimental since it's only useable with experimental API... */ 178 /** 179 * CoglFeatureID: 180 * @COGL_FEATURE_ID_TEXTURE_RG: Support for 181 * %COGL_TEXTURE_COMPONENTS_RG as the internal components of a 182 * texture. 183 * @COGL_FEATURE_ID_UNSIGNED_INT_INDICES: Set if 184 * %COGL_INDICES_TYPE_UNSIGNED_INT is supported in 185 * cogl_indices_new(). 186 * @COGL_FEATURE_ID_MAP_BUFFER_FOR_READ: Whether cogl_buffer_map() is 187 * supported with CoglBufferAccess including read support. 188 * @COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE: Whether cogl_buffer_map() is 189 * supported with CoglBufferAccess including write support. 190 * @COGL_FEATURE_ID_BUFFER_AGE: Available if the age of #CoglOnscreen back 191 * buffers are tracked and so cogl_onscreen_get_buffer_age() can be 192 * expected to return age values other than 0. 193 * @COGL_FEATURE_ID_BLIT_FRAMEBUFFER: Whether blitting using 194 * cogl_blit_framebuffer() is supported. 195 * 196 * All the capabilities that can vary between different GPUs supported 197 * by Cogl. Applications that depend on any of these features should explicitly 198 * check for them using cogl_has_feature() or cogl_has_features(). 199 * 200 * Since: 1.10 201 */ 202 typedef enum _CoglFeatureID 203 { 204 COGL_FEATURE_ID_UNSIGNED_INT_INDICES, 205 COGL_FEATURE_ID_MAP_BUFFER_FOR_READ, 206 COGL_FEATURE_ID_MAP_BUFFER_FOR_WRITE, 207 COGL_FEATURE_ID_FENCE, 208 COGL_FEATURE_ID_TEXTURE_RG, 209 COGL_FEATURE_ID_BUFFER_AGE, 210 COGL_FEATURE_ID_TEXTURE_EGL_IMAGE_EXTERNAL, 211 COGL_FEATURE_ID_BLIT_FRAMEBUFFER, 212 COGL_FEATURE_ID_TIMESTAMP_QUERY, 213 COGL_FEATURE_ID_GET_GPU_TIME, 214 215 /*< private >*/ 216 _COGL_N_FEATURE_IDS /*< skip >*/ 217 } CoglFeatureID; 218 219 220 /** 221 * cogl_has_feature: 222 * @context: A #CoglContext pointer 223 * @feature: A #CoglFeatureID 224 * 225 * Checks if a given @feature is currently available 226 * 227 * Cogl does not aim to be a lowest common denominator API, it aims to 228 * expose all the interesting features of GPUs to application which 229 * means applications have some responsibility to explicitly check 230 * that certain features are available before depending on them. 231 * 232 * Returns: %TRUE if the @feature is currently supported or %FALSE if 233 * not. 234 * 235 * Since: 1.10 236 * Stability: unstable 237 */ 238 COGL_EXPORT gboolean 239 cogl_has_feature (CoglContext *context, CoglFeatureID feature); 240 241 /** 242 * cogl_has_features: 243 * @context: A #CoglContext pointer 244 * @...: A 0 terminated list of CoglFeatureID<!-- -->s 245 * 246 * Checks if a list of features are all currently available. 247 * 248 * This checks all of the listed features using cogl_has_feature() and 249 * returns %TRUE if all the features are available or %FALSE 250 * otherwise. 251 * 252 * Return value: %TRUE if all the features are available, %FALSE 253 * otherwise. 254 * 255 * Since: 1.10 256 * Stability: unstable 257 */ 258 COGL_EXPORT gboolean 259 cogl_has_features (CoglContext *context, ...); 260 261 /** 262 * CoglFeatureCallback: 263 * @feature: A single feature currently supported by Cogl 264 * @user_data: A private pointer passed to cogl_foreach_feature(). 265 * 266 * A callback used with cogl_foreach_feature() for enumerating all 267 * context level features supported by Cogl. 268 * 269 * Since: 0.10 270 * Stability: unstable 271 */ 272 typedef void (*CoglFeatureCallback) (CoglFeatureID feature, void *user_data); 273 274 /** 275 * cogl_foreach_feature: 276 * @context: A #CoglContext pointer 277 * @callback: (scope call): A #CoglFeatureCallback called for each 278 * supported feature 279 * @user_data: (closure): Private data to pass to the callback 280 * 281 * Iterates through all the context level features currently supported 282 * for a given @context and for each feature @callback is called. 283 * 284 * Since: 1.10 285 * Stability: unstable 286 */ 287 COGL_EXPORT void 288 cogl_foreach_feature (CoglContext *context, 289 CoglFeatureCallback callback, 290 void *user_data); 291 292 /** 293 * CoglGraphicsResetStatus: 294 * @COGL_GRAPHICS_RESET_STATUS_NO_ERROR: 295 * @COGL_GRAPHICS_RESET_STATUS_GUILTY_CONTEXT_RESET: 296 * @COGL_GRAPHICS_RESET_STATUS_INNOCENT_CONTEXT_RESET: 297 * @COGL_GRAPHICS_RESET_STATUS_UNKNOWN_CONTEXT_RESET: 298 * @COGL_GRAPHICS_RESET_STATUS_PURGED_CONTEXT_RESET: 299 * 300 * All the error values that might be returned by 301 * cogl_get_graphics_reset_status(). Each value's meaning corresponds 302 * to the similarly named value defined in the ARB_robustness and 303 * NV_robustness_video_memory_purge extensions. 304 */ 305 typedef enum _CoglGraphicsResetStatus 306 { 307 COGL_GRAPHICS_RESET_STATUS_NO_ERROR, 308 COGL_GRAPHICS_RESET_STATUS_GUILTY_CONTEXT_RESET, 309 COGL_GRAPHICS_RESET_STATUS_INNOCENT_CONTEXT_RESET, 310 COGL_GRAPHICS_RESET_STATUS_UNKNOWN_CONTEXT_RESET, 311 COGL_GRAPHICS_RESET_STATUS_PURGED_CONTEXT_RESET, 312 } CoglGraphicsResetStatus; 313 314 /** 315 * cogl_get_graphics_reset_status: 316 * @context: a #CoglContext pointer 317 * 318 * Returns the graphics reset status as reported by 319 * GetGraphicsResetStatusARB defined in the ARB_robustness extension. 320 * 321 * Note that Cogl doesn't normally enable the ARB_robustness 322 * extension in which case this will only ever return 323 * #COGL_GRAPHICS_RESET_STATUS_NO_ERROR. 324 * 325 * Applications must explicitly use a backend specific method to 326 * request that errors get reported such as X11's 327 * cogl_xlib_renderer_request_reset_on_video_memory_purge(). 328 * 329 * Return value: a #CoglGraphicsResetStatus 330 */ 331 COGL_EXPORT CoglGraphicsResetStatus 332 cogl_get_graphics_reset_status (CoglContext *context); 333 334 /** 335 * cogl_context_is_hardware_accelerated: 336 * @context: a #CoglContext pointer 337 * 338 * Returns: %TRUE if the @context is hardware accelerated, or %FALSE if 339 * not. 340 */ 341 COGL_EXPORT gboolean 342 cogl_context_is_hardware_accelerated (CoglContext *context); 343 344 typedef const char * const CoglPipelineKey; 345 346 /** 347 * cogl_context_set_named_pipeline: 348 * @context: a #CoglContext pointer 349 * @key: a #CoglPipelineKey pointer 350 * @pipeline: (nullable): a #CoglPipeline to associate with the @context and 351 * @key 352 * 353 * Associate a #CoglPipeline with a @context and @key. This will not take a new 354 * reference to the @pipeline, but will unref all associated pipelines when 355 * the @context gets destroyed. Similarly, if a pipeline gets overwritten, 356 * it will get unreffed as well. 357 */ 358 COGL_EXPORT void 359 cogl_context_set_named_pipeline (CoglContext *context, 360 CoglPipelineKey *key, 361 CoglPipeline *pipeline); 362 363 /** 364 * cogl_context_get_named_pipeline: 365 * @context: a #CoglContext pointer 366 * @key: a #CoglPipelineKey pointer 367 * 368 * Return value: (transfer none): The #CoglPipeline associated with the 369 * given @context and @key, or %NULL if no such #CoglPipeline 370 * was found. 371 */ 372 COGL_EXPORT CoglPipeline * 373 cogl_context_get_named_pipeline (CoglContext *context, 374 CoglPipelineKey *key); 375 376 COGL_EXPORT void 377 cogl_context_free_timestamp_query (CoglContext *context, 378 CoglTimestampQuery *query); 379 380 COGL_EXPORT int64_t 381 cogl_context_timestamp_query_get_time_ns (CoglContext *context, 382 CoglTimestampQuery *query); 383 384 /** 385 * cogl_context_get_gpu_time_ns: 386 * @context: a #CoglContext pointer 387 * 388 * This function should only be called if the COGL_FEATURE_ID_GET_GPU_TIME 389 * feature is advertised. 390 * 391 * Return value: Current GPU time in nanoseconds 392 */ 393 COGL_EXPORT int64_t 394 cogl_context_get_gpu_time_ns (CoglContext *context); 395 396 G_END_DECLS 397 398 #endif /* __COGL_CONTEXT_H__ */ 399 400