4 * An object oriented GL/GLES Abstraction/Utility Layer
6 * Copyright (C) 2007,2008,2009 Intel Corporation.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
24 #if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
25 #error "Only <cogl/cogl.h> can be included directly."
28 #ifndef __COGL_PIPELINE_LAYER_STATE_H__
29 #define __COGL_PIPELINE_LAYER_STATE_H__
31 #include <cogl/cogl-pipeline.h>
32 #include <cogl/cogl-color.h>
33 #include <cogl/cogl-matrix.h>
34 #include <cogl/cogl-texture.h>
39 #ifdef COGL_ENABLE_EXPERIMENTAL_API
43 * @COGL_PIPELINE_FILTER_NEAREST: Measuring in manhatten distance from the,
44 * current pixel center, use the nearest texture texel
45 * @COGL_PIPELINE_FILTER_LINEAR: Use the weighted average of the 4 texels
46 * nearest the current pixel center
47 * @COGL_PIPELINE_FILTER_NEAREST_MIPMAP_NEAREST: Select the mimap level whose
48 * texel size most closely matches the current pixel, and use the
49 * %COGL_PIPELINE_FILTER_NEAREST criterion
50 * @COGL_PIPELINE_FILTER_LINEAR_MIPMAP_NEAREST: Select the mimap level whose
51 * texel size most closely matches the current pixel, and use the
52 * %COGL_PIPELINE_FILTER_LINEAR criterion
53 * @COGL_PIPELINE_FILTER_NEAREST_MIPMAP_LINEAR: Select the two mimap levels
54 * whose texel size most closely matches the current pixel, use
55 * the %COGL_PIPELINE_FILTER_NEAREST criterion on each one and take
56 * their weighted average
57 * @COGL_PIPELINE_FILTER_LINEAR_MIPMAP_LINEAR: Select the two mimap levels
58 * whose texel size most closely matches the current pixel, use
59 * the %COGL_PIPELINE_FILTER_LINEAR criterion on each one and take
60 * their weighted average
62 * Texture filtering is used whenever the current pixel maps either to more
63 * than one texture element (texel) or less than one. These filter enums
64 * correspond to different strategies used to come up with a pixel color, by
65 * possibly referring to multiple neighbouring texels and taking a weighted
66 * average or simply using the nearest texel.
69 COGL_PIPELINE_FILTER_NEAREST = 0x2600,
70 COGL_PIPELINE_FILTER_LINEAR = 0x2601,
71 COGL_PIPELINE_FILTER_NEAREST_MIPMAP_NEAREST = 0x2700,
72 COGL_PIPELINE_FILTER_LINEAR_MIPMAP_NEAREST = 0x2701,
73 COGL_PIPELINE_FILTER_NEAREST_MIPMAP_LINEAR = 0x2702,
74 COGL_PIPELINE_FILTER_LINEAR_MIPMAP_LINEAR = 0x2703
76 /* NB: these values come from the equivalents in gl.h */
79 * CoglPipelineWrapMode:
80 * @COGL_PIPELINE_WRAP_MODE_REPEAT: The texture will be repeated. This
81 * is useful for example to draw a tiled background.
82 * @COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE: The coordinates outside the
83 * range 0→1 will sample copies of the edge pixels of the
84 * texture. This is useful to avoid artifacts if only one copy of
85 * the texture is being rendered.
86 * @COGL_PIPELINE_WRAP_MODE_AUTOMATIC: Cogl will try to automatically
87 * decide which of the above two to use. For cogl_rectangle(), it
88 * will use repeat mode if any of the texture coordinates are
89 * outside the range 0→1, otherwise it will use clamp to edge. For
90 * cogl_polygon() it will always use repeat mode. For
91 * cogl_vertex_buffer_draw() it will use repeat mode except for
92 * layers that have point sprite coordinate generation enabled. This
93 * is the default value.
95 * The wrap mode specifies what happens when texture coordinates
96 * outside the range 0→1 are used. Note that if the filter mode is
97 * anything but %COGL_PIPELINE_FILTER_NEAREST then texels outside the
98 * range 0→1 might be used even when the coordinate is exactly 0 or 1
99 * because OpenGL will try to sample neighbouring pixels. For example
100 * if you are trying to render the full texture then you may get
101 * artifacts around the edges when the pixels from the other side are
102 * merged in if the wrap mode is set to repeat.
106 /* GL_ALWAYS is just used here as a value that is known not to clash
107 * with any valid GL wrap modes
109 * XXX: keep the values in sync with the CoglPipelineWrapModeInternal
110 * enum so no conversion is actually needed.
113 COGL_PIPELINE_WRAP_MODE_REPEAT = 0x2901,
114 COGL_PIPELINE_WRAP_MODE_MIRRORED_REPEAT = 0x8370,
115 COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE = 0x812F,
116 COGL_PIPELINE_WRAP_MODE_AUTOMATIC = 0x0207 /* GL_ALWAYS */
117 } CoglPipelineWrapMode;
118 /* NB: these values come from the equivalents in gl.h */
121 * cogl_pipeline_set_layer:
122 * @pipeline: A #CoglPipeline object
123 * @layer_index: the index of the layer
124 * @texture: a #CoglTexture for the layer object
126 * In addition to the standard OpenGL lighting model a Cogl pipeline may have
127 * one or more layers comprised of textures that can be blended together in
128 * order, with a number of different texture combine modes. This function
129 * defines a new texture layer.
131 * The index values of multiple layers do not have to be consecutive; it is
132 * only their relative order that is important.
134 * The @texture parameter can also be %NULL in which case the pipeline
135 * will use a default white texture. The type of the default texture
136 * will be the same as whatever texture was last used for the pipeline
137 * or %COGL_TEXTURE_TYPE_2D if none has been specified yet. To
138 * explicitly specify the type of default texture required, use
139 * cogl_pipeline_set_layer_null_texture() instead.
141 * <note>In the future, we may define other types of pipeline layers, such
142 * as purely GLSL based layers.</note>
145 * Stability: unstable
148 cogl_pipeline_set_layer_texture (CoglPipeline *pipeline,
150 CoglTexture *texture);
153 * cogl_pipeline_set_layer_null_texture:
154 * @pipeline: A #CoglPipeline
155 * @layer_index: The layer number to modify
156 * @texture_type: The type of the default texture to use
158 * Sets the texture for this layer to be the default texture for the
159 * given type. This is equivalent to calling
160 * cogl_pipeline_set_layer_texture() with %NULL for the texture
161 * argument except that you can also specify the type of default
162 * texture to use. The default texture is a 1x1 pixel white texture.
164 * This function is mostly useful if you want to create a base
165 * pipeline that you want to create multiple copies from using
166 * cogl_pipeline_copy(). In that case this function can be used to
167 * specify the texture type so that any pipeline copies can share the
168 * internal texture type state for efficiency.
171 * Stability: unstable
174 cogl_pipeline_set_layer_null_texture (CoglPipeline *pipeline,
176 CoglTextureType texure_type);
179 * cogl_pipeline_get_layer_texture:
180 * @pipeline: A #CoglPipeline object
181 * @layer_index: the index of the layer
183 * Return value: the texture that was set for the given layer of the
184 * pipeline or %NULL if no texture was set.
185 * Stability: unstable
189 cogl_pipeline_get_layer_texture (CoglPipeline *pipeline,
193 * cogl_pipeline_remove_layer:
194 * @pipeline: A #CoglPipeline object
195 * @layer_index: Specifies the layer you want to remove
197 * This function removes a layer from your pipeline
199 * Stability: unstable
202 cogl_pipeline_remove_layer (CoglPipeline *pipeline,
206 * cogl_pipeline_set_layer_combine:
207 * @pipeline: A #CoglPipeline object
208 * @layer_index: Specifies the layer you want define a combine function for
209 * @blend_string: A <link linkend="cogl-Blend-Strings">Cogl blend string</link>
210 * describing the desired texture combine function.
211 * @error: A #GError that may report parse errors or lack of GPU/driver
212 * support. May be %NULL, in which case a warning will be printed out if an
213 * error is encountered.
215 * If not already familiar; you can refer
216 * <link linkend="cogl-Blend-Strings">here</link> for an overview of what blend
217 * strings are and there syntax.
219 * These are all the functions available for texture combining:
221 * <listitem>REPLACE(arg0) = arg0</listitem>
222 * <listitem>MODULATE(arg0, arg1) = arg0 x arg1</listitem>
223 * <listitem>ADD(arg0, arg1) = arg0 + arg1</listitem>
224 * <listitem>ADD_SIGNED(arg0, arg1) = arg0 + arg1 - 0.5</listitem>
225 * <listitem>INTERPOLATE(arg0, arg1, arg2) = arg0 x arg2 + arg1 x (1 - arg2)</listitem>
226 * <listitem>SUBTRACT(arg0, arg1) = arg0 - arg1</listitem>
229 * DOT3_RGB(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
230 * (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
231 * (arg0[B] - 0.5)) * (arg1[B] - 0.5))
236 * DOT3_RGBA(arg0, arg1) = 4 x ((arg0[R] - 0.5)) * (arg1[R] - 0.5) +
237 * (arg0[G] - 0.5)) * (arg1[G] - 0.5) +
238 * (arg0[B] - 0.5)) * (arg1[B] - 0.5))
244 * <link linkend="cogl-Blend-String-syntax">color-source syntax</link> for
245 * describing the arguments. The valid source names for texture combining
249 * <term>TEXTURE</term>
250 * <listitem>Use the color from the current texture layer</listitem>
253 * <term>TEXTURE_0, TEXTURE_1, etc</term>
254 * <listitem>Use the color from the specified texture layer</listitem>
257 * <term>CONSTANT</term>
258 * <listitem>Use the color from the constant given with
259 * cogl_pipeline_set_layer_constant()</listitem>
262 * <term>PRIMARY</term>
263 * <listitem>Use the color of the pipeline as set with
264 * cogl_pipeline_set_color()</listitem>
267 * <term>PREVIOUS</term>
268 * <listitem>Either use the texture color from the previous layer, or
269 * if this is layer 0, use the color of the pipeline as set with
270 * cogl_pipeline_set_color()</listitem>
274 * <refsect2 id="cogl-Layer-Combine-Examples">
275 * <title>Layer Combine Examples</title>
276 * <para>This is effectively what the default blending is:</para>
277 * <informalexample><programlisting>
278 * RGBA = MODULATE (PREVIOUS, TEXTURE)
279 * </programlisting></informalexample>
280 * <para>This could be used to cross-fade between two images, using
281 * the alpha component of a constant as the interpolator. The constant
282 * color is given by calling cogl_pipeline_set_layer_constant.</para>
283 * <informalexample><programlisting>
284 * RGBA = INTERPOLATE (PREVIOUS, TEXTURE, CONSTANT[A])
285 * </programlisting></informalexample>
288 * <note>You can't give a multiplication factor for arguments as you can
289 * with blending.</note>
291 * Return value: %TRUE if the blend string was successfully parsed, and the
292 * described texture combining is supported by the underlying driver and
293 * or hardware. On failure, %FALSE is returned and @error is set
296 * Stability: unstable
299 cogl_pipeline_set_layer_combine (CoglPipeline *pipeline,
301 const char *blend_string,
305 * cogl_pipeline_set_layer_combine_constant:
306 * @pipeline: A #CoglPipeline object
307 * @layer_index: Specifies the layer you want to specify a constant used
308 * for texture combining
309 * @constant: The constant color you want
311 * When you are using the 'CONSTANT' color source in a layer combine
312 * description then you can use this function to define its value.
315 * Stability: unstable
318 cogl_pipeline_set_layer_combine_constant (CoglPipeline *pipeline,
320 const CoglColor *constant);
323 * cogl_pipeline_set_layer_matrix:
324 * @pipeline: A #CoglPipeline object
325 * @layer_index: the index for the layer inside @pipeline
326 * @matrix: the transformation matrix for the layer
328 * This function lets you set a matrix that can be used to e.g. translate
329 * and rotate a single layer of a pipeline used to fill your geometry.
332 * Stability: unstable
335 cogl_pipeline_set_layer_matrix (CoglPipeline *pipeline,
337 const CoglMatrix *matrix);
340 * cogl_pipeline_get_n_layers:
341 * @pipeline: A #CoglPipeline object
343 * Retrieves the number of layers defined for the given @pipeline
345 * Return value: the number of layers
348 * Stability: unstable
351 cogl_pipeline_get_n_layers (CoglPipeline *pipeline);
354 * cogl_pipeline_set_layer_filters:
355 * @pipeline: A #CoglPipeline object
356 * @layer_index: the layer number to change.
357 * @min_filter: the filter used when scaling a texture down.
358 * @mag_filter: the filter used when magnifying a texture.
360 * Changes the decimation and interpolation filters used when a texture is
361 * drawn at other scales than 100%.
364 * Stability: unstable
367 cogl_pipeline_set_layer_filters (CoglPipeline *pipeline,
369 CoglPipelineFilter min_filter,
370 CoglPipelineFilter mag_filter);
373 * cogl_pipeline_get_layer_min_filter:
374 * @pipeline: A #CoglPipeline object
375 * @layer_index: the layer number to change.
377 * Retrieves the currently set minification #CoglPipelineFilter set on
378 * the specified layer. The miniifcation filter determines how the
379 * layer should be sampled when down-scaled.
381 * The default filter is %COGL_PIPELINE_FILTER_LINEAR but this can be
382 * changed using cogl_pipeline_set_layer_filters().
384 * Return value: The minification #CoglPipelineFilter for the
387 * Stability: unstable
390 cogl_pipeline_get_layer_min_filter (CoglPipeline *pipeline,
394 * cogl_pipeline_get_layer_mag_filter:
395 * @pipeline: A #CoglPipeline object
396 * @layer_index: the layer number to change.
398 * Retrieves the currently set magnification #CoglPipelineFilter set on
399 * the specified layer. The magnification filter determines how the
400 * layer should be sampled when up-scaled.
402 * The default filter is %COGL_PIPELINE_FILTER_LINEAR but this can be
403 * changed using cogl_pipeline_set_layer_filters().
405 * Return value: The magnification #CoglPipelineFilter for the
408 * Stability: unstable
411 cogl_pipeline_get_layer_mag_filter (CoglPipeline *pipeline,
415 * cogl_pipeline_set_layer_point_sprite_coords_enabled:
416 * @pipeline: a #CoglHandle to a pipeline.
417 * @layer_index: the layer number to change.
418 * @enable: whether to enable point sprite coord generation.
419 * @error: A return location for a GError, or NULL to ignore errors.
421 * When rendering points, if @enable is %TRUE then the texture
422 * coordinates for this layer will be replaced with coordinates that
423 * vary from 0.0 to 1.0 across the primitive. The top left of the
424 * point will have the coordinates 0.0,0.0 and the bottom right will
425 * have 1.0,1.0. If @enable is %FALSE then the coordinates will be
426 * fixed for the entire point.
428 * This function will only work if %COGL_FEATURE_POINT_SPRITE is
429 * available. If the feature is not available then the function will
430 * return %FALSE and set @error.
432 * Return value: %TRUE if the function succeeds, %FALSE otherwise.
434 * Stability: unstable
437 cogl_pipeline_set_layer_point_sprite_coords_enabled (CoglPipeline *pipeline,
443 * cogl_pipeline_get_layer_point_sprite_coords_enabled:
444 * @pipeline: a #CoglHandle to a pipeline.
445 * @layer_index: the layer number to check.
447 * Gets whether point sprite coordinate generation is enabled for this
450 * Return value: whether the texture coordinates will be replaced with
451 * point sprite coordinates.
454 * Stability: unstable
457 cogl_pipeline_get_layer_point_sprite_coords_enabled (CoglPipeline *pipeline,
461 * cogl_pipeline_get_layer_wrap_mode_s:
462 * @pipeline: A #CoglPipeline object
463 * @layer_index: the layer number to change.
465 * Returns the wrap mode for the 's' coordinate of texture lookups on this
468 * Return value: the wrap mode for the 's' coordinate of texture lookups on
472 * Stability: unstable
475 cogl_pipeline_get_layer_wrap_mode_s (CoglPipeline *pipeline,
479 * cogl_pipeline_set_layer_wrap_mode_s:
480 * @pipeline: A #CoglPipeline object
481 * @layer_index: the layer number to change.
482 * @mode: the new wrap mode
484 * Sets the wrap mode for the 's' coordinate of texture lookups on this layer.
487 * Stability: unstable
490 cogl_pipeline_set_layer_wrap_mode_s (CoglPipeline *pipeline,
492 CoglPipelineWrapMode mode);
495 * cogl_pipeline_get_layer_wrap_mode_t:
496 * @pipeline: A #CoglPipeline object
497 * @layer_index: the layer number to change.
499 * Returns the wrap mode for the 't' coordinate of texture lookups on this
502 * Return value: the wrap mode for the 't' coordinate of texture lookups on
506 * Stability: unstable
509 cogl_pipeline_get_layer_wrap_mode_t (CoglPipeline *pipeline,
514 * cogl_pipeline_set_layer_wrap_mode_t:
515 * @pipeline: A #CoglPipeline object
516 * @layer_index: the layer number to change.
517 * @mode: the new wrap mode
519 * Sets the wrap mode for the 't' coordinate of texture lookups on this layer.
522 * Stability: unstable
525 cogl_pipeline_set_layer_wrap_mode_t (CoglPipeline *pipeline,
527 CoglPipelineWrapMode mode);
530 * cogl_pipeline_get_layer_wrap_mode_p:
531 * @pipeline: A #CoglPipeline object
532 * @layer_index: the layer number to change.
534 * Returns the wrap mode for the 'p' coordinate of texture lookups on this
537 * Return value: the wrap mode for the 'p' coordinate of texture lookups on
541 * Stability: unstable
544 cogl_pipeline_get_layer_wrap_mode_p (CoglPipeline *pipeline,
548 * cogl_pipeline_set_layer_wrap_mode_p:
549 * @pipeline: A #CoglPipeline object
550 * @layer_index: the layer number to change.
551 * @mode: the new wrap mode
553 * Sets the wrap mode for the 'p' coordinate of texture lookups on
554 * this layer. 'p' is the third coordinate.
557 * Stability: unstable
560 cogl_pipeline_set_layer_wrap_mode_p (CoglPipeline *pipeline,
562 CoglPipelineWrapMode mode);
565 * cogl_pipeline_set_layer_wrap_mode:
566 * @pipeline: A #CoglPipeline object
567 * @layer_index: the layer number to change.
568 * @mode: the new wrap mode
570 * Sets the wrap mode for all three coordinates of texture lookups on
571 * this layer. This is equivalent to calling
572 * cogl_pipeline_set_layer_wrap_mode_s(),
573 * cogl_pipeline_set_layer_wrap_mode_t() and
574 * cogl_pipeline_set_layer_wrap_mode_p() separately.
577 * Stability: unstable
580 cogl_pipeline_set_layer_wrap_mode (CoglPipeline *pipeline,
582 CoglPipelineWrapMode mode);
585 * cogl_pipeline_add_layer_snippet:
586 * @pipeline: A #CoglPipeline
587 * @layer: The layer to hook the snippet to
588 * @snippet: A #CoglSnippet
590 * Adds a shader snippet that will hook on to the given layer of the
591 * pipeline. The exact part of the pipeline that the snippet wraps
592 * around depends on the hook that is given to
593 * cogl_snippet_new(). Note that some hooks can't be used with a layer
594 * and need to be added with cogl_pipeline_add_snippet() instead.
597 * Stability: Unstable
600 cogl_pipeline_add_layer_snippet (CoglPipeline *pipeline,
602 CoglSnippet *snippet);
604 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
608 #endif /* __COGL_PIPELINE_LAYER_STATE_H__ */