## MetaCompositor MetaCompositor — Compositor API |

## Synopsis

    enum                MetaCompEffect;
                        MetaCompositor;
    MetaCompositor *    meta_compositor_new                 (MetaDisplay *display);
    void                meta_compositor_destroy             (MetaCompositor *compositor);
    void                meta_compositor_manage_screen       (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    void                meta_compositor_unmanage_screen     (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    void                meta_compositor_window_shape_changed
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window);
    gboolean            meta_compositor_process_event       (MetaCompositor *compositor,
                                                             XEvent *event,
                                                             MetaWindow *window);
    gboolean            meta_compositor_filter_keybinding   (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaKeyBinding *binding);
    void                meta_compositor_add_window          (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_remove_window       (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_show_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);
    void                meta_compositor_hide_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);
    void                meta_compositor_switch_workspace    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *from,
                                                             MetaWorkspace *to,
                                                             MetaMotionDirection direction);
    void                meta_compositor_maximize_window     (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);
    void                meta_compositor_unmaximize_window   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);
    void                meta_compositor_window_mapped       (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_window_unmapped     (MetaCompositor *compositor,
                                                             MetaWindow *window);
    void                meta_compositor_sync_window_geometry
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean did_placement);
    void                meta_compositor_set_updates_frozen  (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean updates_frozen);
    void                meta_compositor_queue_frame_drawn   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean no_delay_frame);
    void                meta_compositor_sync_stack          (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             GList *stack);
    void                meta_compositor_sync_screen_size    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             guint width,
                                                             guint height);
    void                meta_compositor_flash_screen        (MetaCompositor *compositor,
                                                             MetaScreen *screen);
    ClutterActor *      meta_get_stage_for_screen           (MetaScreen *screen);
    ClutterActor *      meta_get_overlay_group_for_screen   (MetaScreen *screen);
    Window              meta_get_overlay_window             (MetaScreen *screen);
    GList *             meta_get_window_actors              (MetaScreen *screen);
    ClutterActor *      meta_get_window_group_for_screen    (MetaScreen *screen);
    ClutterActor *      meta_get_top_window_group_for_screen
                                                            (MetaScreen *screen);
    void                meta_disable_unredirect_for_screen  (MetaScreen *screen);
    void                meta_enable_unredirect_for_screen   (MetaScreen *screen);
    void                meta_set_stage_input_region         (MetaScreen *screen,
                                                             XserverRegion region);
    void                meta_empty_stage_input_region       (MetaScreen *screen);

## Description

At a high-level, a window is not-visible or visible. When a window is added (with `meta_compositor_add_window()`) it is not visible. `meta_compositor_show_window()` indicates a transition from not-visible to visible. Some of the reasons for this:

- Window newly created

- Window is unminimized

- Window is moved to the current desktop

- Window was made sticky

`meta_compositor_hide_window()` indicates that the window has transitioned from visible to not-visible. Some reasons include:

- Window was destroyed

- Window is minimized

- Window is moved to a different desktop

- Window no longer sticky.

Note that combinations are possible - a window might have first been minimized and then moved to a different desktop. The 'effect' parameter to `meta_compositor_show_window()` and `meta_compositor_hide_window()` is a hint as to the appropriate effect to show the user and should not be considered to be indicative of a state change.

When the active workspace is changed, `meta_compositor_switch_workspace()` is called first, then `meta_compositor_show_window()` and `meta_compositor_hide_window()` are called individually for each window affected, with an effect of META_COMP_EFFECT_NONE. If hiding windows will affect the switch workspace animation, the compositor needs to delay hiding the windows until the switch workspace animation completes.

`meta_compositor_maximize_window()` and `meta_compositor_unmaximize_window()` are transitions within the visible state. The window is resized __before__ the call, so it may be necessary to readjust the display based on the old_rect to start the animation.

`meta_compositor_window_mapped()` and `meta_compositor_window_unmapped()` are notifications when the toplevel window (frame or client window) is mapped or unmapped. That is, when the result of `meta_window_toplevel_is_mapped()` changes. The main use of this is to drop resources when a window is unmapped. A window will always be mapped before `meta_compositor_show_window()` is called and will not be unmapped until after `meta_compositor_hide_window()` is called. If the live_hidden_windows preference is set, windows will never be unmapped.

### Containers

There's three containers in the stage that can be used to place actors, here are listed in the order in which they are painted:

- window group, accessible with `meta_get_window_group_for_screen()`

- top window group, accessible with `meta_get_top_window_group_for_screen()`

- overlay group, accessible with `meta_get_overlay_group_for_screen()`

Mutter will place actors representing windows in the window group, except for override-redirect windows (ie. popups and menus) which will be placed in the top window group. Mutter won't put any actors in the overlay group, but it's intended for compositors to place there panel, dashes, status bars, etc.

## Details

### enum MetaCompEffect

    typedef enum {
      META_COMP_EFFECT_CREATE,
      META_COMP_EFFECT_UNMINIMIZE,
      META_COMP_EFFECT_DESTROY,
      META_COMP_EFFECT_MINIMIZE,
      META_COMP_EFFECT_NONE
    } MetaCompEffect;

Indicates the appropriate effect to show the user for `meta_compositor_show_window()` and `meta_compositor_hide_window()`

`META_COMP_EFFECT_CREATE` | The window is newly created (also used for a window that was previously on a different workspace and is changed to become visible on the active workspace.)
`META_COMP_EFFECT_UNMINIMIZE` | The window should be shown as unminimizing from its icon geometry.
`META_COMP_EFFECT_DESTROY` | The window is being destroyed
`META_COMP_EFFECT_MINIMIZE` | The window should be shown as minimizing to its icon geometry.
`META_COMP_EFFECT_NONE` | No effect, the window should be shown or hidden immediately.

### MetaCompositor

    typedef struct _MetaCompositor MetaCompositor;

### meta_compositor_new ()

    MetaCompositor *    meta_compositor_new                 (MetaDisplay *display);

### meta_compositor_destroy ()

    void                meta_compositor_destroy             (MetaCompositor *compositor);

### meta_compositor_manage_screen ()

    void                meta_compositor_manage_screen       (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_compositor_unmanage_screen ()

    void                meta_compositor_unmanage_screen     (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_compositor_window_shape_changed ()

    void                meta_compositor_window_shape_changed
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_process_event ()

    gboolean            meta_compositor_process_event       (MetaCompositor *compositor,
                                                             XEvent *event,
                                                             MetaWindow *window);

### meta_compositor_filter_keybinding ()

    gboolean            meta_compositor_filter_keybinding   (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaKeyBinding *binding);

### meta_compositor_add_window ()

    void                meta_compositor_add_window          (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_remove_window ()

    void                meta_compositor_remove_window       (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_show_window ()

    void                meta_compositor_show_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);

### meta_compositor_hide_window ()

    void                meta_compositor_hide_window         (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaCompEffect effect);

### meta_compositor_switch_workspace ()

    void                meta_compositor_switch_workspace    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             MetaWorkspace *from,
                                                             MetaWorkspace *to,
                                                             MetaMotionDirection direction);

### meta_compositor_maximize_window ()

    void                meta_compositor_maximize_window     (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);

### meta_compositor_unmaximize_window ()

    void                meta_compositor_unmaximize_window   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             MetaRectangle *old_rect,
                                                             MetaRectangle *new_rect);

### meta_compositor_window_mapped ()

    void                meta_compositor_window_mapped       (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_window_unmapped ()

    void                meta_compositor_window_unmapped     (MetaCompositor *compositor,
                                                             MetaWindow *window);

### meta_compositor_sync_window_geometry ()

    void                meta_compositor_sync_window_geometry
                                                            (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean did_placement);

### meta_compositor_set_updates_frozen ()

    void                meta_compositor_set_updates_frozen  (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean updates_frozen);

### meta_compositor_queue_frame_drawn ()

    void                meta_compositor_queue_frame_drawn   (MetaCompositor *compositor,
                                                             MetaWindow *window,
                                                             gboolean no_delay_frame);

### meta_compositor_sync_stack ()

    void                meta_compositor_sync_stack          (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             GList *stack);

### meta_compositor_sync_screen_size ()

    void                meta_compositor_sync_screen_size    (MetaCompositor *compositor,
                                                             MetaScreen *screen,
                                                             guint width,
                                                             guint height);

### meta_compositor_flash_screen ()

    void                meta_compositor_flash_screen        (MetaCompositor *compositor,
                                                             MetaScreen *screen);

### meta_get_stage_for_screen ()

    ClutterActor *      meta_get_stage_for_screen           (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The ClutterStage for the screen. [transfer none]

### meta_get_overlay_group_for_screen ()

    ClutterActor *      meta_get_overlay_group_for_screen   (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The overlay group corresponding to `screen`. [transfer none]

### meta_get_overlay_window ()

    Window              meta_get_overlay_window             (MetaScreen *screen);

`screen` : | a MetaScreen

### meta_get_window_actors ()

    GList *             meta_get_window_actors              (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The set of MetaWindowActor on `screen`. [transfer none][element-type Clutter.Actor]

### meta_get_window_group_for_screen ()

    ClutterActor *      meta_get_window_group_for_screen    (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The window group corresponding to `screen`. [transfer none]

### meta_get_top_window_group_for_screen ()

    ClutterActor *      meta_get_top_window_group_for_screen
                                                            (MetaScreen *screen);

`screen` : | a MetaScreen
Returns : | The top window group corresponding to `screen`. [transfer none]

### meta_disable_unredirect_for_screen ()

    void                meta_disable_unredirect_for_screen  (MetaScreen *screen);

Disables unredirection, can be usefull in situations where having unredirected windows is undesireable like when recording a video.

`screen` : | a MetaScreen

### meta_enable_unredirect_for_screen ()

    void                meta_enable_unredirect_for_screen   (MetaScreen *screen);

Enables unredirection which reduces the overhead for apps like games.

`screen` : | a MetaScreen

### meta_set_stage_input_region ()

    void                meta_set_stage_input_region         (MetaScreen *screen,
                                                             XserverRegion region);

### meta_empty_stage_input_region ()

    void                meta_empty_stage_input_region       (MetaScreen *screen);