isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-12-26 12:52:14 +00:00
Code Issues Packages Projects Releases Wiki Activity
6840b3a4c7
mutter/clutter/clutter-offscreen-effect.h

123 lines
4.6 KiB
C
Raw Normal View History

effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
/*
* Clutter.
*
* An OpenGL based 'interactive canvas' library.
*
* Copyright (C) 2010 Intel Corporation.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
* Author:
* Emmanuele Bassi <ebassi@linux.intel.com>
*/
Move header inclusion guard at the top GCC has some optimization for the inclusion guard, but they only work if the check is the outermost one. We're fairly inconsistent because of historical reasons, so we should ensure that we follow the same pattern in every public header.
2015-07-07 14:51:13 +00:00
#ifndef __CLUTTER_OFFSCREEN_EFFECT_H__
#define __CLUTTER_OFFSCREEN_EFFECT_H__
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
#error "Only <clutter/clutter.h> can be included directly."
#endif
build: Re-arrange headers Try to minimize the included headers, especially in clutter-actor.h.
2010-11-18 18:23:49 +00:00
#include <cogl/cogl.h>
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
#include <clutter/clutter-effect.h>
Reduce our internal dependence on the Cogl 1.x api Since Cogl has started restricting what cogl 1.x api is exposed when COGL_ENABLE_EXPERIMENTAL_2_0_API is defined and since we build all Clutter internals with COGL_ENABLE_EXPERIMENTAL_2_0_API defined this patch makes a first pass at reducing our internal use of the Cogl 1.x api. The most notable api that's no longer exposed to us internally is the cogl_material_ api so this switches all Clutter internals to use the cogl_pipeline_ api instead. This patch also makes quite a bit of progress removing internal uses of CoglHandle although there is still more to go.
2012-02-21 15:55:51 +00:00
#include <clutter/clutter-cogl-compat.h>
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
G_BEGIN_DECLS
#define CLUTTER_TYPE_OFFSCREEN_EFFECT (clutter_offscreen_effect_get_type ())
#define CLUTTER_OFFSCREEN_EFFECT(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), CLUTTER_TYPE_OFFSCREEN_EFFECT, ClutterOffscreenEffect))
#define CLUTTER_IS_OFFSCREEN_EFFECT(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), CLUTTER_TYPE_OFFSCREEN_EFFECT))
#define CLUTTER_OFFSCREEN_EFFECT_CLASS(k) (G_TYPE_CHECK_CLASS_CAST ((k), CLUTTER_TYPE_OFFSCREEN_EFFECT, ClutterOffscreenEffectClass))
#define CLUTTER_IS_OFFSCREEN_EFFECT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), CLUTTER_TYPE_OFFSCREEN_EFFECT))
#define CLUTTER_OFFSCREEN_EFFECT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), CLUTTER_TYPE_OFFSCREEN_EFFECT, ClutterOffscreenEffectClass))
typedef struct _ClutterOffscreenEffect ClutterOffscreenEffect;
typedef struct _ClutterOffscreenEffectPrivate ClutterOffscreenEffectPrivate;
typedef struct _ClutterOffscreenEffectClass ClutterOffscreenEffectClass;
/**
* ClutterOffscreenEffect:
*
* The #ClutterOffscreenEffect structure contains only private data
* and should be accessed using the provided API
*
* Since: 1.4
*/
struct _ClutterOffscreenEffect
{
/*< private >*/
ClutterEffect parent_instance;
ClutterOffscreenEffectPrivate *priv;
};
/**
* ClutterOffscreenEffectClass:
offscreen-effect: Rename create_target to create_buffer *** This is an API change *** The create_target() virtual function should return a CoglHandle to a texture; clutter_offscreen_effect_get_target(), instead, returns a CoglMaterial to be painted in the implementation of the paint_target() virtual function. Instead of equating textures with materials, and confusing the user of the API, we should mark the difference more prominently. First of all, we should return a CoglMaterial* (now that we have that as a public type) in get_target(); having handles all over the place does not make it easier to distinguish the semantics of the virtual functions. Then we should rename create_target() to create_texture(), to make it clear that what should be returned is a texture that is used as the backing for the offscreen framebuffer.
2010-09-01 16:56:15 +00:00
* @create_texture: virtual function
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
* @paint_target: virtual function
*
* The #ClutterOffscreenEffectClass structure contains only private data
*
* Since: 1.4
*/
struct _ClutterOffscreenEffectClass
{
/*< private >*/
ClutterEffectClass parent_class;
/*< public >*/
offscreen-effect: Rename create_target to create_buffer *** This is an API change *** The create_target() virtual function should return a CoglHandle to a texture; clutter_offscreen_effect_get_target(), instead, returns a CoglMaterial to be painted in the implementation of the paint_target() virtual function. Instead of equating textures with materials, and confusing the user of the API, we should mark the difference more prominently. First of all, we should return a CoglMaterial* (now that we have that as a public type) in get_target(); having handles all over the place does not make it easier to distinguish the semantics of the virtual functions. Then we should rename create_target() to create_texture(), to make it clear that what should be returned is a texture that is used as the backing for the offscreen framebuffer.
2010-09-01 16:56:15 +00:00
CoglHandle (* create_texture) (ClutterOffscreenEffect *effect,
Reduce the amount of g-ir-scanner warnings As much as we can; the remaining warnings are mostly valid things that the introspection scanner still flags as potential issues.
2010-12-09 12:36:50 +00:00
gfloat width,
gfloat height);
void (* paint_target) (ClutterOffscreenEffect *effect);
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
/*< private >*/
void (* _clutter_offscreen1) (void);
void (* _clutter_offscreen2) (void);
void (* _clutter_offscreen3) (void);
void (* _clutter_offscreen4) (void);
void (* _clutter_offscreen5) (void);
void (* _clutter_offscreen6) (void);
void (* _clutter_offscreen7) (void);
};
Annotate all public symbols We are going to switch to compiler annotations to determine the visibility of the symbols.
2014-03-17 18:19:52 +00:00
CLUTTER_AVAILABLE_IN_1_4
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
GType clutter_offscreen_effect_get_type (void) G_GNUC_CONST;
Annotate all public symbols We are going to switch to compiler annotations to determine the visibility of the symbols.
2014-03-17 18:19:52 +00:00
CLUTTER_AVAILABLE_IN_1_4
offscreen-effect: Add public accessor for target size The OffscreenEffect class needs to expose a way for sub-classes to track the size of FBO it creates, in case it has to do some geometry deformations like the DeformEffect sub-classes. Let's move the private symbol we used internally in 1.6 to fix DeformEffect to the list of public symbols of OffscreenEffect. http://bugzilla.clutter-project.org/show_bug.cgi?id=2570
2011-02-28 14:31:59 +00:00
CoglMaterial * clutter_offscreen_effect_get_target (ClutterOffscreenEffect *effect);
Annotate all functions available since 1.10
2012-02-27 16:31:53 +00:00
CLUTTER_AVAILABLE_IN_1_10
offscreen-effect: Add clutter_offscreen_effect_get_texture Sometimes a subclass of ClutterOffscreenEffect wants to paint with a completely custom material. In that case it is awkward to modify the material returned owned by ClutterOffscreenEffect so it makes more sense to just get the texture and manage its own material. Reviewed-by: Emmanuele Bassi <ebassi@linux.intel.com>
2011-11-28 11:53:54 +00:00
CoglHandle clutter_offscreen_effect_get_texture (ClutterOffscreenEffect *effect);
Annotate all public symbols We are going to switch to compiler annotations to determine the visibility of the symbols.
2014-03-17 18:19:52 +00:00
CLUTTER_AVAILABLE_IN_1_4
offscreen-effect: Add public accessor for target size The OffscreenEffect class needs to expose a way for sub-classes to track the size of FBO it creates, in case it has to do some geometry deformations like the DeformEffect sub-classes. Let's move the private symbol we used internally in 1.6 to fix DeformEffect to the list of public symbols of OffscreenEffect. http://bugzilla.clutter-project.org/show_bug.cgi?id=2570
2011-02-28 14:31:59 +00:00
void clutter_offscreen_effect_paint_target (ClutterOffscreenEffect *effect);
Annotate all public symbols We are going to switch to compiler annotations to determine the visibility of the symbols.
2014-03-17 18:19:52 +00:00
CLUTTER_AVAILABLE_IN_1_4
offscreen-effect: Add public accessor for target size The OffscreenEffect class needs to expose a way for sub-classes to track the size of FBO it creates, in case it has to do some geometry deformations like the DeformEffect sub-classes. Let's move the private symbol we used internally in 1.6 to fix DeformEffect to the list of public symbols of OffscreenEffect. http://bugzilla.clutter-project.org/show_bug.cgi?id=2570
2011-02-28 14:31:59 +00:00
CoglHandle clutter_offscreen_effect_create_texture (ClutterOffscreenEffect *effect,
gfloat width,
gfloat height);
offscreen-effect: Add a method to get the target area The target size is not always enough, there are cases where the offset used to paint the target must also be available for developers implementing an OffscreenEffect. The get_target_rect() method returns the rectangle used to paint the target, with the offsets in the ClutterRect:origin and the texture size in the ClutterRect:size fields, respectively. The get_target_size() method should be deprecated, given that its replacement is generally more useful. https://bugzilla.gnome.org/show_bug.cgi?id=670004
2013-02-21 13:01:58 +00:00
CLUTTER_DEPRECATED_IN_1_14_FOR (clutter_offscreen_effect_get_target_rect)
offscreen-effect: Add public accessor for target size The OffscreenEffect class needs to expose a way for sub-classes to track the size of FBO it creates, in case it has to do some geometry deformations like the DeformEffect sub-classes. Let's move the private symbol we used internally in 1.6 to fix DeformEffect to the list of public symbols of OffscreenEffect. http://bugzilla.clutter-project.org/show_bug.cgi?id=2570
2011-02-28 14:31:59 +00:00
gboolean clutter_offscreen_effect_get_target_size (ClutterOffscreenEffect *effect,
gfloat *width,
gfloat *height);
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
offscreen-effect: Add a method to get the target area The target size is not always enough, there are cases where the offset used to paint the target must also be available for developers implementing an OffscreenEffect. The get_target_rect() method returns the rectangle used to paint the target, with the offsets in the ClutterRect:origin and the texture size in the ClutterRect:size fields, respectively. The get_target_size() method should be deprecated, given that its replacement is generally more useful. https://bugzilla.gnome.org/show_bug.cgi?id=670004
2013-02-21 13:01:58 +00:00
CLUTTER_AVAILABLE_IN_1_14
gboolean clutter_offscreen_effect_get_target_rect (ClutterOffscreenEffect *effect,
ClutterRect *rect);
effect: Add OffscreenEffect The OffscreenEffect class is meant to be used to implement Effect sub-classes that create an offscreen framebuffer and redirect the actor's paint sequence there. The OffscreenEffect is useful for effects using fragment shaders. Any shader-based effect being applied to an actor through an offscreen buffer should be used before painting the resulting target material and not for every actor. This means that doing: pre_paint: cogl_program_use(program) set up offscreen buffer paint: [ actors ] → offscreen buffer → target material post_paint: paint target material cogl_program_use(null) Is not correct. Unfortunately, we cannot really do: post_paint: cogl_program_use(program) paint target material cogl_program_use(null) Because the OffscreenEffect::post_paint() implementation also pops the offscreen buffer and re-instates the previous framebuffer: post_paint: cogl_program_use(program) change frame buffer ← ouch! paint target material cogl_program_use(null) One way to fix it is to allow using the shader right before painting the target material - which means adding a new virtual inside the OffscreenEffect class vtable in additions to the ones defined by the parent Effect class. The newly-added paint_target() virtual allows the correct sequence of actions by adding an entry point for sub-classes to wrap the "paint target material" operation with custom code, in order to implement the case above correctly as: post_paint: change frame buffer cogl_program_use(program) paint target material cogl_program_use(null) The added upside is that sub-classes of OffscreenEffect involving shaders really just need to override the prepare() and paint_target() virtuals, since the pre_paint() and post_paint() do all that's needed.
2010-05-17 10:39:27 +00:00
G_END_DECLS
#endif /* __CLUTTER_OFFSCREEN_EFFECT_H__ */
Reference in New Issue Copy Permalink