1 /* 2 * Cogl 3 * 4 * A Low Level GPU Graphics and Utilities API 5 * 6 * Copyright (C) 2007,2008,2009 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_PIPELINE_H__ 36 #define __COGL_PIPELINE_H__ 37 38 /* We forward declare the CoglPipeline type here to avoid some circular 39 * dependency issues with the following headers. 40 */ 41 typedef struct _CoglPipeline CoglPipeline; 42 43 #include <cogl/cogl-types.h> 44 #include <cogl/cogl-context.h> 45 #include <cogl/cogl-snippet.h> 46 47 #include <glib-object.h> 48 49 G_BEGIN_DECLS 50 51 /** 52 * SECTION:cogl-pipeline 53 * @short_description: Functions for creating and manipulating the GPU 54 * pipeline 55 * 56 * Cogl allows creating and manipulating objects representing the full 57 * configuration of the GPU pipeline. In simplified terms the GPU 58 * pipeline takes primitive geometry as the input, it first performs 59 * vertex processing, allowing you to deform your geometry, then 60 * rasterizes that (turning it from pure geometry into fragments) then 61 * performs fragment processing including depth testing and texture 62 * mapping. Finally it blends the result with the framebuffer. 63 */ 64 65 #define COGL_PIPELINE(OBJECT) ((CoglPipeline *)OBJECT) 66 67 /** 68 * cogl_pipeline_get_gtype: 69 * 70 * Returns: a #GType that can be used with the GLib type system. 71 */ 72 COGL_EXPORT 73 GType cogl_pipeline_get_gtype (void); 74 75 /** 76 * cogl_pipeline_new: (constructor) 77 * @context: a #CoglContext 78 * 79 * Allocates and initializes a default simple pipeline that will color 80 * a primitive white. 81 * 82 * Return value: (transfer full): a pointer to a new #CoglPipeline 83 * 84 * Since: 2.0 85 * Stability: Unstable 86 */ 87 COGL_EXPORT CoglPipeline * 88 cogl_pipeline_new (CoglContext *context); 89 90 /** 91 * cogl_pipeline_copy: 92 * @source: a #CoglPipeline object to copy 93 * 94 * Creates a new pipeline with the configuration copied from the 95 * source pipeline. 96 * 97 * We would strongly advise developers to always aim to use 98 * cogl_pipeline_copy() instead of cogl_pipeline_new() whenever there will 99 * be any similarity between two pipelines. Copying a pipeline helps Cogl 100 * keep track of a pipelines ancestry which we may use to help minimize GPU 101 * state changes. 102 * 103 * Return value: (transfer full): a pointer to the newly allocated #CoglPipeline 104 * 105 * Since: 2.0 106 * Stability: Unstable 107 */ 108 COGL_EXPORT CoglPipeline * 109 cogl_pipeline_copy (CoglPipeline *source); 110 111 /** 112 * cogl_is_pipeline: 113 * @object: A #CoglObject 114 * 115 * Gets whether the given @object references an existing pipeline object. 116 * 117 * Return value: %TRUE if the @object references a #CoglPipeline, 118 * %FALSE otherwise 119 * 120 * Since: 2.0 121 * Stability: Unstable 122 */ 123 COGL_EXPORT gboolean 124 cogl_is_pipeline (void *object); 125 126 /** 127 * CoglPipelineLayerCallback: 128 * @pipeline: The #CoglPipeline whose layers are being iterated 129 * @layer_index: The current layer index 130 * @user_data: The private data passed to cogl_pipeline_foreach_layer() 131 * 132 * The callback prototype used with cogl_pipeline_foreach_layer() for 133 * iterating all the layers of a @pipeline. 134 * 135 * Since: 2.0 136 * Stability: Unstable 137 */ 138 typedef gboolean (*CoglPipelineLayerCallback) (CoglPipeline *pipeline, 139 int layer_index, 140 void *user_data); 141 142 /** 143 * cogl_pipeline_foreach_layer: 144 * @pipeline: A #CoglPipeline object 145 * @callback: (scope call): A #CoglPipelineLayerCallback to be 146 * called for each layer index 147 * @user_data: (closure): Private data that will be passed to the 148 * callback 149 * 150 * Iterates all the layer indices of the given @pipeline. 151 * 152 * Since: 2.0 153 * Stability: Unstable 154 */ 155 COGL_EXPORT void 156 cogl_pipeline_foreach_layer (CoglPipeline *pipeline, 157 CoglPipelineLayerCallback callback, 158 void *user_data); 159 160 /** 161 * cogl_pipeline_get_uniform_location: 162 * @pipeline: A #CoglPipeline object 163 * @uniform_name: The name of a uniform 164 * 165 * This is used to get an integer representing the uniform with the 166 * name @uniform_name. The integer can be passed to functions such as 167 * cogl_pipeline_set_uniform_1f() to set the value of a uniform. 168 * 169 * This function will always return a valid integer. Ie, unlike 170 * OpenGL, it does not return -1 if the uniform is not available in 171 * this pipeline so it can not be used to test whether uniforms are 172 * present. It is not necessary to set the program on the pipeline 173 * before calling this function. 174 * 175 * Return value: A integer representing the location of the given uniform. 176 * 177 * Since: 2.0 178 * Stability: Unstable 179 */ 180 COGL_EXPORT int 181 cogl_pipeline_get_uniform_location (CoglPipeline *pipeline, 182 const char *uniform_name); 183 184 G_END_DECLS 185 186 #endif /* __COGL_PIPELINE_H__ */ 187