From 0478c225b7627ed06c6460b0e11772e867d86579 Mon Sep 17 00:00:00 2001 From: Niels De Graef Date: Fri, 19 Oct 2018 09:15:54 +0200 Subject: [PATCH] Add some gtk-doc comments. --- clutter/clutter/clutter-stage-window.c | 28 +++++ clutter/clutter/clutter-stage.c | 36 +++++- src/backends/meta-backend.c | 42 +++++++ src/backends/meta-cursor-tracker.c | 8 ++ src/backends/meta-logical-monitor.c | 19 +++ src/backends/meta-monitor-manager-private.h | 54 +++++++-- src/backends/meta-monitor-manager.c | 114 ++++++++++++++++++ src/backends/meta-pointer-constraint.c | 26 ++++ src/backends/meta-pointer-constraint.h | 5 + src/backends/meta-renderer-view.c | 13 ++ src/backends/meta-renderer.c | 47 ++++++++ src/backends/native/meta-backend-native.c | 10 ++ .../native/meta-clutter-backend-native.c | 14 +++ .../native/meta-monitor-manager-kms.c | 12 ++ src/backends/x11/meta-backend-x11.c | 9 ++ .../x11/meta-monitor-manager-xrandr.c | 12 ++ src/compositor/meta-surface-actor.c | 10 +- src/compositor/meta-window-actor.c | 15 ++- src/core/window.c | 34 +++++- .../meta-pointer-confinement-wayland.c | 10 ++ src/wayland/meta-pointer-lock-wayland.c | 9 ++ 21 files changed, 505 insertions(+), 22 deletions(-) diff --git a/clutter/clutter/clutter-stage-window.c b/clutter/clutter/clutter-stage-window.c index aa47d480d..1786c7842 100644 --- a/clutter/clutter/clutter-stage-window.c +++ b/clutter/clutter/clutter-stage-window.c @@ -6,6 +6,14 @@ #include "clutter-stage-window.h" #include "clutter-private.h" +/** + * SECTION:clutter-stage-window + * @short_description: Handles the implementation for ClutterStage + * + * #ClutterStageWindow is an interface that provides the implementation for the + * #ClutterStage actor, abstracting away the specifics of the windowing system. + */ + #define clutter_stage_window_get_type _clutter_stage_window_get_type typedef ClutterStageWindowIface ClutterStageWindowInterface; @@ -36,6 +44,12 @@ clutter_stage_window_default_init (ClutterStageWindowInterface *iface) g_object_interface_install_property (iface, pspec); } +/** + * _clutter_stage_window_get_wrapper: + * @window: a #ClutterStageWindow object + * + * Returns the pointer to the #ClutterStage it's part of. + */ ClutterActor * _clutter_stage_window_get_wrapper (ClutterStageWindow *window) { @@ -138,6 +152,14 @@ _clutter_stage_window_schedule_update (ClutterStageWindow *window, iface->schedule_update (window, sync_delay); } +/** + * _clutter_stage_window_get_update_time: + * @window: a #ClutterStageWindow object + * + * See _clutter_stage_get_update_time() for more info. + * + * Returns: The timestamp of the update time + */ gint64 _clutter_stage_window_get_update_time (ClutterStageWindow *window) { @@ -155,6 +177,12 @@ _clutter_stage_window_get_update_time (ClutterStageWindow *window) return iface->get_update_time (window); } +/** + * _clutter_stage_window_clear_update_time: + * @window: a #ClutterStageWindow object + * + * Clears the update time. See _clutter_stage_clear_update_time() for more info. + */ void _clutter_stage_window_clear_update_time (ClutterStageWindow *window) { diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c index dcadeb24f..d1107149e 100644 --- a/clutter/clutter/clutter-stage.c +++ b/clutter/clutter/clutter-stage.c @@ -36,10 +36,10 @@ * using clutter_actor_destroy(), which will take care of destroying all the * actors contained inside them. * - * #ClutterStage is a proxy actor, wrapping the backend-specific - * implementation of the windowing system. It is possible to subclass - * #ClutterStage, as long as every overridden virtual function chains up to - * the parent class corresponding function. + * #ClutterStage is a proxy actor, wrapping the backend-specific implementation + * (a #StageWindow) of the windowing system. It is possible to subclass + * #ClutterStage, as long as every overridden virtual function chains up to the + * parent class corresponding function. */ #include "clutter-build-config.h" @@ -2249,6 +2249,8 @@ clutter_stage_class_init (ClutterStageClass *klass) * @stage: the stage that received the event * @frame_event: a #CoglFrameEvent * @frame_info: a #ClutterFrameInfo + * + * Signals that the #ClutterStage was presented on the screen to the user. */ stage_signals[PRESENTED] = g_signal_new (I_("presented"), @@ -3989,6 +3991,12 @@ clutter_stage_get_minimum_size (ClutterStage *stage, *height_p = (guint) height; } +/** + * _clutter_stage_schedule_update: + * @window: a #ClutterStage actor + * + * Schedules a redraw of the #ClutterStage at the next optimal timestamp. + */ void _clutter_stage_schedule_update (ClutterStage *stage) { @@ -4005,7 +4013,18 @@ _clutter_stage_schedule_update (ClutterStage *stage) stage->priv->sync_delay); } -/* Returns the earliest time the stage is ready to update */ +/** + * _clutter_stage_get_update_time: + * @stage: a #ClutterStage actor + * + * Returns the earliest time in which the stage is ready to update. The update + * time is set when _clutter_stage_schedule_update() is called. This can then + * be used by e.g. the #ClutterMasterClock to know when the stage needs to be + * redrawn. + * + * Returns: -1 if no redraw is needed; 0 if the backend doesn't know, or the + * timestamp (in microseconds) otherwise. + */ gint64 _clutter_stage_get_update_time (ClutterStage *stage) { @@ -4021,6 +4040,13 @@ _clutter_stage_get_update_time (ClutterStage *stage) return _clutter_stage_window_get_update_time (stage_window); } +/** + * _clutter_stage_clear_update_time: + * @stage: a #ClutterStage actor + * + * Resets the update time. Call this after a redraw, so that the update time + * can again be updated. + */ void _clutter_stage_clear_update_time (ClutterStage *stage) { diff --git a/src/backends/meta-backend.c b/src/backends/meta-backend.c index 709d4194c..8987da1e3 100644 --- a/src/backends/meta-backend.c +++ b/src/backends/meta-backend.c @@ -22,6 +22,31 @@ * Jasper St. Pierre */ +/** + * SECTION:meta-backend + * @title: MetaBackend + * @short_description: Handles monitor config, modesetting, cursor sprites, ... + * + * MetaBackend is the abstraction that deals with several things like: + * - Modesetting (depending on the backend, this can be done either by X or KMS) + * - Initializing the #MetaSettings + * - Setting up Monitor configuration + * - Input device configuration (using the #ClutterDeviceManager) + * - Creating the #MetaRenderer + * - Setting up the stage of the scene graph (using #MetaStage) + * - Creating the object that deals wih the cursor (using #MetaCursorTracker) + * and its possible pointer constraint (using #MetaPointerConstraint) + * - Setting the cursor sprite (using #MetaCursorRenderer) + * - Interacting with logind (using the appropriate D-Bus interface) + * - Querying UPower (over D-Bus) to know when the lid is closed + * - Setup Remote Desktop / Screencasting (#MetaRemoteDesktop) + * - Setup the #MetaEgl object + * + * Note that the #MetaBackend is not a subclass of #ClutterBackend. It is + * responsible for creating the correct one, based on the backend that is + * used (#MetaBackendNative or #MetaBackendX11). + */ + #include "config.h" #include "backends/meta-backend-private.h" @@ -1138,6 +1163,15 @@ meta_backend_get_client_pointer_constraint (MetaBackend *backend) return priv->client_pointer_constraint; } +/** + * meta_backend_set_client_pointer_constraint: + * @backend: a #MetaBackend object. + * @constraint: (nullable): the client constraint to follow. + * + * Sets the current pointer constraint and removes (and unrefs) the previous + * one. If @constrant is %NULL, this means that there is no + * #MetaPointerConstraint active. + */ void meta_backend_set_client_pointer_constraint (MetaBackend *backend, MetaPointerConstraint *constraint) @@ -1260,6 +1294,14 @@ meta_clutter_init (void) meta_backend_post_init (_backend); } +/** + * meta_is_stage_views_enabled: + * + * Returns whether the #ClutterStage can be rendered using multiple stage views. + * In practice, this means we can define a separate framebuffer for each + * #MetaLogicalMonitor, rather than rendering everything into a single + * framebuffer. For example: in X11, onle one single framebuffer is allowed. + */ gboolean meta_is_stage_views_enabled (void) { diff --git a/src/backends/meta-cursor-tracker.c b/src/backends/meta-cursor-tracker.c index d33fa300a..1a3501935 100644 --- a/src/backends/meta-cursor-tracker.c +++ b/src/backends/meta-cursor-tracker.c @@ -311,6 +311,14 @@ meta_cursor_tracker_unset_window_cursor (MetaCursorTracker *tracker) set_window_cursor (tracker, FALSE, NULL); } +/** + * meta_cursor_tracker_set_root_cursor: + * @tracker: a #MetaCursorTracker object. + * @cursor_sprite: (transfer none): the new root cursor + * + * Sets the root cursor (the cursor that is shown if not modified by a window). + * The #MetaCursorTracker will take a strong reference to the sprite. + */ void meta_cursor_tracker_set_root_cursor (MetaCursorTracker *tracker, MetaCursorSprite *cursor_sprite) diff --git a/src/backends/meta-logical-monitor.c b/src/backends/meta-logical-monitor.c index 1b6151638..99a35f7f3 100644 --- a/src/backends/meta-logical-monitor.c +++ b/src/backends/meta-logical-monitor.c @@ -19,6 +19,25 @@ * 02111-1307, USA. */ +/** + * SECTION:meta-logical-monitor + * @title: MetaLogicalMonitor + * @short_description: An abstraction for a monitor(set) and its configuration. + * + * A logical monitor is a group of one or more physical monitors that + * must behave and be treated as single one. This happens, for example, + * when 2 monitors are mirrored. Each physical monitor is represented + * by a #MetaMonitor. + * + * #MetaLogicalMonitor has a single viewport, with its owns transformations + * (such as scaling), that are applied to all the #MetaMonitors that + * are grouped by it. + * + * #MetaLogicalMonitor provides an abstraction that makes it easy to handle + * the specifics of setting up different #MetaMonitors. It then can + * be used more easily by #MetaRendererView. + */ + #include "config.h" #include "backends/meta-logical-monitor.h" diff --git a/src/backends/meta-monitor-manager-private.h b/src/backends/meta-monitor-manager-private.h index 69c3036c4..becb78eef 100644 --- a/src/backends/meta-monitor-manager-private.h +++ b/src/backends/meta-monitor-manager-private.h @@ -1,17 +1,5 @@ /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */ -/** - * \file screen-private.h Handling of monitor configuration - * - * Managing multiple monitors - * This file contains structures and functions that handle - * multiple monitors, including reading the current configuration - * and available hardware, and applying it. - * - * This interface is private to mutter, API users should look - * at MetaScreen instead. - */ - /* * Copyright (C) 2001 Havoc Pennington * Copyright (C) 2003 Rob Adams @@ -152,6 +140,48 @@ struct _MetaMonitorManager MetaMonitorSwitchConfigType current_switch_config; }; +/** + * MetaMonitorManagerClass: + * + * @read_edid: Returns the raw Extended Display Identification Data (EDID) + * for the given #MetaOutput object. Use meta_output_parse_edid() to parse + * afterwards. + * + * @ensure_initial_config: Called on setup. Makes sure an initial config + * is loaded. + * + * @apply_monitors_config: Tries to apply the given config using the given + * method. Throws an error if something went wrong. + * + * @set_power_save_mode: Sets the #MetaPowerSave mode (for all displays). + * + * @change_backlight: Changes the backlight intensity to the given value (in + * percent). + * + * @get_crtc_gamma: Queries and returns the gamma rampQueries and returns the + * gamma ramp. + * + * @set_crtc_gamma: Sets custom display LUT (look up table) for each primary + * color. Each table is indexed by a value that represents input intensity, + * and yields a value that represents output intensity. + * + * @tiled_monitor_added: Should be called by a #MetaMonitor when it is created. + * + * @tiled_monitor_removed: Should be called by a #MetaMonitor when it is + * destroyed. + * + * @is_transform_handled: vfunc for + * meta_monitor_manager_is_transform_handled(). + * @calculate_monitor_mode_scale: vfunc for + * meta_monitor_manager_calculate_monitor_mode_scale(). + * @calculate_supported_scales: vfunc for + * meta_monitor_manager_calculate_supported_scales(). + * @get_capabilities: vfunc for meta_monitor_manager_get_capabilities(). + * @get_max_screen_size: vfunc for meta_monitor_manager_get_max_screen_size(). + * @get_default_layout_mode: vfunc for meta_monitor_manager_get_default_layout_mode(). + * + * The base class for a #MetaMonitorManager. + */ struct _MetaMonitorManagerClass { MetaDBusDisplayConfigSkeletonClass parent_class; diff --git a/src/backends/meta-monitor-manager.c b/src/backends/meta-monitor-manager.c index cc70271f1..919ac3b52 100644 --- a/src/backends/meta-monitor-manager.c +++ b/src/backends/meta-monitor-manager.c @@ -23,6 +23,20 @@ * along with this program; if not, see . */ +/** + * SECTION:meta-monitor-manager + * @title: MetaMonitorManager + * @short_description: A manager for multiple monitors + * + * #MetaMonitorManager is an abstract class which contains methods to handle + * multiple monitors (both #MetaMonitor and #MetaLogicalMonitor) and GPU's + * (#MetaGpu). Its functions include reading and/or changing the current + * configuration and available capabiliies. + * + * The #MetaMonitorManager also provides the "org.gnome.Mutter.DisplayConfig" + * DBus service, so apps like GNOME Settings can use this functionality. + */ + #include "config.h" #include "backends/meta-monitor-manager-private.h" @@ -354,6 +368,15 @@ lid_is_closed_changed (MetaBackend *backend, meta_monitor_manager_lid_is_closed_changed (manager); } +/** + * meta_monitor_manager_is_headless: + * @manager: A #MetaMonitorManager object + * + * Returns whether the monitor manager is headless, i.e. without + * any #MetaLogicalMonitors attached to it. + * + * Returns: %TRUE if no monitors are attached, %FALSE otherwise. + */ gboolean meta_monitor_manager_is_headless (MetaMonitorManager *manager) { @@ -390,6 +413,14 @@ meta_monitor_manager_calculate_supported_scales (MetaMonitorManager *ma n_supported_scales); } +/** + * meta_monitor_manager_get_capabilities: + * @manager: A #MetaMonitorManager object + * + * Queries the capabilities of the monitor manager. + * + * Returns: #MetaMonitorManagerCapability flags representing the capabilities. + */ MetaMonitorManagerCapability meta_monitor_manager_get_capabilities (MetaMonitorManager *manager) { @@ -2295,12 +2326,31 @@ meta_monitor_manager_get (void) return meta_backend_get_monitor_manager (backend); } +/** + * meta_monitor_manager_get_num_logical_monitors: + * @manager: A #MetaMonitorManager object + * + * Returns the number of #MetaLogicalMonitors (can be 0 in case of a + * headless setup). + * + * Returns: the total number of #MetaLogicalMonitors. + */ int meta_monitor_manager_get_num_logical_monitors (MetaMonitorManager *manager) { return g_list_length (manager->logical_monitors); } +/** + * meta_monitor_manager_get_logical_monitors: + * @manager: A #MetaMonitorManager object + * + * Returns the list of #MetaLogicalMonitors that is handled. See also + * meta_monitor_manager_get_num_logical_monitors() if you only need the size of + * the list. + * + * Returns: (transfer none) (nullable): the list of logical monitors. + */ GList * meta_monitor_manager_get_logical_monitors (MetaMonitorManager *manager) { @@ -2341,12 +2391,30 @@ find_monitor (MetaMonitorManager *monitor_manager, return NULL; } +/** + * meta_monitor_manager_get_primary_monitor: + * @manager: A #MetaMonitorManager object + * + * Returns the primary monitor. This can be %NULL (e.g. when running headless). + * + * Returns: (transfer none) (nullable): The primary #MetaMonitor, or %NULL if + * none. + */ MetaMonitor * meta_monitor_manager_get_primary_monitor (MetaMonitorManager *manager) { return find_monitor (manager, meta_monitor_is_primary); } +/** + * meta_monitor_manager_get_laptop_panel: + * @manager: A #MetaMonitorManager object + * + * Returns the #MetaMonitor that represents the built-in laptop panel (if + * applicable). + * + * Returns: (transfer none) (nullable): The laptop panel, or %NULL if none. + */ MetaMonitor * meta_monitor_manager_get_laptop_panel (MetaMonitorManager *manager) { @@ -2395,6 +2463,18 @@ meta_monitor_manager_get_monitor_from_spec (MetaMonitorManager *manager, return NULL; } +/** + * meta_monitor_manager_get_logical_monitor_at: + * @manager: A #MetaMonitorManager object + * @x: The x-coordinate + * @y: The y-coordinate + * + * Finds the #MetaLogicalMonitor at the given @x and @y coordinates in the + * total layout. + * + * Returns: (transfer none) (nullable): The #MetaLogicalMonitor at the given + * point, or %NULL if none. + */ MetaLogicalMonitor * meta_monitor_manager_get_logical_monitor_at (MetaMonitorManager *manager, float x, @@ -2413,6 +2493,17 @@ meta_monitor_manager_get_logical_monitor_at (MetaMonitorManager *manager, return NULL; } +/** + * meta_monitor_manager_get_logical_monitor_from_rect: + * @manager: A #MetaMonitorManager object + * @rect: The rectangle + * + * Finds the #MetaLogicalMonitor which has the largest area in common with the + * given @rect in the total layout. + * + * Returns: (transfer none) (nullable): The #MetaLogicalMonitor which + * corresponds the most to the given @rect, or %NULL if none. + */ MetaLogicalMonitor * meta_monitor_manager_get_logical_monitor_from_rect (MetaMonitorManager *manager, MetaRectangle *rect) @@ -2472,12 +2563,29 @@ meta_monitor_manager_get_logical_monitor_neighbor (MetaMonitorManager *manager, return NULL; } +/** + * meta_monitor_manager_get_monitors: + * @manager: A #MetaMonitorManager object + * + * Returns the list of #MetaMonitors. See also + * meta_monitor_manager_get_logical_monitors() for a list of + * #MetaLogicalMonitors. + * + * Returns: (transfer none) (nullable): the list of #MetaMonitors. + */ GList * meta_monitor_manager_get_monitors (MetaMonitorManager *manager) { return manager->monitors; } +/** + * meta_monitor_manager_get_capabilities: + * @manager: A #MetaMonitorManager object + * + * Should only be called by subclasses. Adds a #MetaGpu to the internal list of + * GPU's. + */ void meta_monitor_manager_add_gpu (MetaMonitorManager *manager, MetaGpu *gpu) @@ -2888,6 +2996,12 @@ meta_monitor_manager_get_monitor_for_connector (MetaMonitorManager *manager, return -1; } +/** + * meta_monitor_manager_get_is_builtin_display_on: + * @manager: A #MetaMonitorManager object + * + * Returns whether the built-in display (i.e. a laptop panel) is turned on. + */ gboolean meta_monitor_manager_get_is_builtin_display_on (MetaMonitorManager *manager) { diff --git a/src/backends/meta-pointer-constraint.c b/src/backends/meta-pointer-constraint.c index 40ee3d32f..55ca9f023 100644 --- a/src/backends/meta-pointer-constraint.c +++ b/src/backends/meta-pointer-constraint.c @@ -22,6 +22,19 @@ * Jonas Ådahl */ +/** + * SECTION:meta-pointer-constraint + * @title: MetaPointerConstraint + * @short_description: Pointer client constraints. + * + * A MetaPointerConstraint can be used to implement any kind of pointer + * constraint as requested by a client, such as cursor lock. + * + * Examples of pointer constraints are "pointer confinement" and "pointer + * locking" (as defined in the wayland pointer constraint protocol extension), + * which restrict movement in relation to a given client. + */ + #include "config.h" #include "backends/meta-pointer-constraint.h" @@ -40,6 +53,19 @@ meta_pointer_constraint_class_init (MetaPointerConstraintClass *klass) { } +/** + * meta_pointer_constraint_constrain: + * @constraint: a #MetaPointerConstraint. + * @device; the device of the pointer. + * @time: the timestamp (in ms) of the event. + * @prev_x: X-coordinate of the previous pointer position. + * @prev_y: Y-coordinate of the previous pointer position. + * @x: The modifiable X-coordinate to which the pointer would like to go to. + * @y: The modifiable Y-coordinate to which the pointer would like to go to. + * + * Constrains the pointer movement from point (@prev_x, @prev_y) to (@x, @y), + * if needed. + */ void meta_pointer_constraint_constrain (MetaPointerConstraint *constraint, ClutterInputDevice *device, diff --git a/src/backends/meta-pointer-constraint.h b/src/backends/meta-pointer-constraint.h index 01bc13758..ed0b025b5 100644 --- a/src/backends/meta-pointer-constraint.h +++ b/src/backends/meta-pointer-constraint.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS G_DECLARE_DERIVABLE_TYPE (MetaPointerConstraint, meta_pointer_constraint, META, POINTER_CONSTRAINT, GObject); +/** + * MetaPointerConstraintClass: + * @constrain: the virtual function pointer for + * meta_pointer_constraint_constrain(). + */ struct _MetaPointerConstraintClass { GObjectClass parent_class; diff --git a/src/backends/meta-renderer-view.c b/src/backends/meta-renderer-view.c index 19ab9efc8..cab1f5f48 100644 --- a/src/backends/meta-renderer-view.c +++ b/src/backends/meta-renderer-view.c @@ -15,6 +15,19 @@ * License along with this library. If not, see . */ +/** + * SECTION:meta-renderer-view + * @title: MetaRendererView + * @short_description: Renders (a part of) the global stage. + * + * A MetaRendererView object is responsible for rendering (a part of) the + * global stage, or more precisely: the part that matches what can be seen on a + * #MetaLogicalMonitor. By splitting up the rendering into different parts and + * attaching it to a #MetaLogicalMonitor, we can do the rendering so that each + * renderer view is responsible for applying the right #MetaMonitorTransform + * and the right scaling. + */ + #include "config.h" #include "backends/meta-renderer-view.h" diff --git a/src/backends/meta-renderer.c b/src/backends/meta-renderer.c index 191897e64..55ada2e95 100644 --- a/src/backends/meta-renderer.c +++ b/src/backends/meta-renderer.c @@ -22,6 +22,24 @@ * Jonas Ådahl */ +/** + * SECTION:meta-renderer + * @title: MetaRenderer + * @short_description: Keeps track of the different renderer views. + * + * A MetaRenderer object has 2 functions: + * + * 1) Keeping a list of #MetaRendererViews, each responsible for + * rendering a part of the stage, corresponding to each #MetaLogicalMonitor. It + * keeps track of this list by querying the list of logical monitors in the + * #MetaBackend's #MetaMonitorManager, and creating a renderer view for each + * logical monitor it encounters. + * + * 2) Creating and setting up an appropriate #CoglRenderer. For example, a + * #MetaRenderer might call cogl_renderer_set_custom_winsys() to tie the + * backend-specific mechanisms into Cogl. + */ + #include "config.h" #include "backends/meta-renderer.h" @@ -37,6 +55,16 @@ typedef struct _MetaRendererPrivate G_DEFINE_TYPE_WITH_PRIVATE (MetaRenderer, meta_renderer, G_TYPE_OBJECT) +/** + * meta_renderer_create_cogl_renderer: + * @renderer: a #MetaRenderer object + * + * Creates a #CoglRenderer that is appropriate for a certain backend. For + * example, a #MetaRenderer might call cogl_renderer_set_custom_winsys() to tie + * the backend-specific mechanisms (such as swapBuffers and vsync) into Cogl. + * + * Returns: (transfer full): a newly made #CoglRenderer. + */ CoglRenderer * meta_renderer_create_cogl_renderer (MetaRenderer *renderer) { @@ -51,6 +79,15 @@ meta_renderer_create_view (MetaRenderer *renderer, logical_monitor); } +/** + * meta_renderer_rebuild_views: + * @renderer: a #MetaRenderer object + * + * Rebuilds the internal list of #MetaRendererView objects by querying the + * current #MetaBackend's #MetaMonitorManager. + * + * This also leads to the original list of monitors being unconditionally freed. + */ void meta_renderer_rebuild_views (MetaRenderer *renderer) { @@ -87,6 +124,16 @@ meta_renderer_set_legacy_view (MetaRenderer *renderer, priv->views = g_list_append (priv->views, legacy_view); } +/** + * meta_renderer_get_views: + * @renderer: a #MetaRenderer object + * + * Returns a list of #MetaRendererView objects, each dealing with a part of the + * stage. + * + * Returns: (transfer-none) (element-type MetaRendererView): a list of + * #MetaRendererView objects. + */ GList * meta_renderer_get_views (MetaRenderer *renderer) { diff --git a/src/backends/native/meta-backend-native.c b/src/backends/native/meta-backend-native.c index b8ea93da9..c473681cb 100644 --- a/src/backends/native/meta-backend-native.c +++ b/src/backends/native/meta-backend-native.c @@ -22,6 +22,16 @@ * Jasper St. Pierre */ +/** + * SECTION:meta-backend-native + * @title: MetaBackendNative + * @short_description: A native (KMS/evdev) MetaBackend + * + * MetaBackendNative is an implementation of #MetaBackend that uses "native" + * technologies like DRM/KMS and libinput/evdev to perform the necessary + * functions. + */ + #include "config.h" #include "backends/native/meta-backend-native.h" diff --git a/src/backends/native/meta-clutter-backend-native.c b/src/backends/native/meta-clutter-backend-native.c index be86eb50e..7d1479053 100644 --- a/src/backends/native/meta-clutter-backend-native.c +++ b/src/backends/native/meta-clutter-backend-native.c @@ -22,6 +22,20 @@ * Jonas Ådahl */ +/** + * SECTION:meta-clutter-backend-native + * @title: MetaClutterBackendNatve + * @short_description: A native backend which renders using EGL. + * + * MetaClutterBackendNative is the #ClutterBackend which is used by the native + * (as opposed to the X) backend. It creates a stage with #MetaStageNative and + * renders using the #CoglRenderer. + * + * Note that MetaClutterBackendNative is something different than a + * #MetaBackendNative. The former is a #ClutterBackend implementation, while + * the latter is a #MetaBackend implementation. + */ + #include "config.h" #include "backends/native/meta-clutter-backend-native.h" diff --git a/src/backends/native/meta-monitor-manager-kms.c b/src/backends/native/meta-monitor-manager-kms.c index 1c4c98360..c04338aac 100644 --- a/src/backends/native/meta-monitor-manager-kms.c +++ b/src/backends/native/meta-monitor-manager-kms.c @@ -22,6 +22,18 @@ * Author: Giovanni Campagna */ +/** + * SECTION:meta-monitor-manager-kms + * @title: MetaMonitorManagerKms + * @short_description: A subclass of #MetaMonitorManager using Linux DRM + * + * #MetaMonitorManagerKms is a subclass of #MetaMonitorManager which + * implements its functionality "natively": it uses the appropriate + * functions of the Linux DRM kernel module and using a udev client. + * + * See also #MetaMonitorManagerXrandr for an implementation using XRandR. + */ + #include "config.h" #include "backends/native/meta-monitor-manager-kms.h" diff --git a/src/backends/x11/meta-backend-x11.c b/src/backends/x11/meta-backend-x11.c index c1c976986..c10365f9d 100644 --- a/src/backends/x11/meta-backend-x11.c +++ b/src/backends/x11/meta-backend-x11.c @@ -22,6 +22,15 @@ * Jasper St. Pierre */ +/** + * SECTION:meta-backend-x11 + * @title: MetaBackendX11 + * @short_description: A X11 MetaBackend + * + * MetaBackendX11 is an implementation of #MetaBackend using X and X + * extensions, like XInput and XKB. + */ + #include "config.h" #include "backends/x11/meta-backend-x11.h" diff --git a/src/backends/x11/meta-monitor-manager-xrandr.c b/src/backends/x11/meta-monitor-manager-xrandr.c index 21ee50e97..246e60334 100644 --- a/src/backends/x11/meta-monitor-manager-xrandr.c +++ b/src/backends/x11/meta-monitor-manager-xrandr.c @@ -23,6 +23,18 @@ * along with this program; if not, see . */ +/** + * SECTION:meta-monitor-manager-xrandr + * @title: MetaMonitorManagerXrandr + * @short_description: A subclass of #MetaMonitorManager using XRadR + * + * #MetaMonitorManagerXrandr is a subclass of #MetaMonitorManager which + * implements its functionality using the RandR X protocol. + * + * See also #MetaMonitorManagerKms for a native implementation using Linux DRM + * and udev. + */ + #include "config.h" #include "backends/x11/meta-monitor-manager-xrandr.h" diff --git a/src/compositor/meta-surface-actor.c b/src/compositor/meta-surface-actor.c index 8d74ae87c..9a7d0ef5b 100644 --- a/src/compositor/meta-surface-actor.c +++ b/src/compositor/meta-surface-actor.c @@ -5,8 +5,14 @@ * @title: MetaSurfaceActor * @short_description: An actor representing a surface in the scene graph * - * A surface can be either a shaped texture, or a group of shaped texture, - * used to draw the content of a window. + * MetaSurfaceActor is an abstract class which represents a surface in the + * Clutter scene graph. A subclass can implement the specifics of a surface + * depending on the way it is handled by a display protocol. + * + * An important feature of #MetaSurfaceActor is that it allows you to set an + * "input region": all events that occur in the surface, but outside of the + * input region are to be explicitly ignored. By default, this region is to + * %NULL, which means events on the whole surface is allowed. */ #include "config.h" diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c index ebfdc6cc3..c0a042aa1 100644 --- a/src/compositor/meta-window-actor.c +++ b/src/compositor/meta-window-actor.c @@ -3,7 +3,20 @@ /** * SECTION:meta-window-actor * @title: MetaWindowActor - * @short_description: An actor representing a top-level window in the scene graph + * @short_description: An actor representing a top-level window in the scene + * graph + * + * #MetaWindowActor is a #ClutterActor that adds a notion of a window to the + * Clutter scene graph. It contains a #MetaWindow which provides the windowing + * API, and the #MetaCompositor that handles it. For the actual content of the + * window, it contains a #MetaSurfaceActor. + * + * #MetaWindowActor takes care of the rendering features you need for your + * window. For example, it will take the windows' requested opacity and use + * that for clutter_actor_set_opacity(). Furthermore, it will also draw a + * shadow around the window (using #MetaShadow) and deal with synchronization + * between events of the window and the actual render loop. See + * MetaWindowActor::first-frame for an example of the latter. */ #include "config.h" diff --git a/src/core/window.c b/src/core/window.c index 60252c4c1..9a8a84a26 100644 --- a/src/core/window.c +++ b/src/core/window.c @@ -21,9 +21,39 @@ */ /** - * SECTION:window + * SECTION:meta-window * @title: MetaWindow - * @short_description: Mutter X managed windows + * @short_description: A display-agnostic abstraction for a window. + * + * #MetaWindow is the core abstraction in Mutter of a window. It has the + * properties you'd expect, such as a title, an icon, whether it's fullscreen, + * has decorations, etc. + * + * Since a lot of different kinds of windows exist, each window also a + * #MetaWindowType which denotes which kind of window we're exactly dealing + * with. For example, one expects slightly different behaviour from a dialog + * than a "normal" window. The type of a window can be queried with + * meta_window_get_type(). + * + * Common API for windows include: + * - Minimizing: meta_window_minimize() / meta_window_unminimize() + * - Maximizing: meta_window_maximize() / meta_window_unmaximize() + * - Fullscreen: meta_window_make_fullscreen() / meta_window_unmake_fullscreen() + * / meta_window_is_fullscreen() + * + * Each #MetaWindow is part of either one or all #MetaWorkspaces of the + * desktop. You can activate a window on a certain workspace using + * meta_window_activate_with_workspace(), and query on which workspace it is + * located using meta_window_located_on_workspace(). The workspace it is part + * of can be obtained using meta_window_get_workspace(). + * + * Each display protocol should make a subclass to be compatible with that + * protocols' specifics, for example #MetaWindowX11 and #MetaWindowWayland. + * This is independent of the protocol that the client uses, which is modeled + * using the #MetaWindowClientType enum. + * + * To integrate within the Clutter scene graph, which deals with the actual + * rendering, each #MetaWindow will be part of a #MetaWindowActor. */ #include "config.h" diff --git a/src/wayland/meta-pointer-confinement-wayland.c b/src/wayland/meta-pointer-confinement-wayland.c index b8a900467..4c1a9f937 100644 --- a/src/wayland/meta-pointer-confinement-wayland.c +++ b/src/wayland/meta-pointer-confinement-wayland.c @@ -22,6 +22,16 @@ * Jonas Ådahl */ +/** + * SECTION:meta-pointer-confinement-wayland + * @title: MetaPointerConfinementWayland + * @short_description: A #MetaPointerConstraint implementing pointer confinement + * + * A MetaPointerConfinementConstraint implements the client pointer constraint + * "pointer confinement": the cursor should not be able to "break out" of a + * certain area defined by the client requesting it. + */ + #include "config.h" #include "wayland/meta-pointer-confinement-wayland.h" diff --git a/src/wayland/meta-pointer-lock-wayland.c b/src/wayland/meta-pointer-lock-wayland.c index a9098d529..08c2789bc 100644 --- a/src/wayland/meta-pointer-lock-wayland.c +++ b/src/wayland/meta-pointer-lock-wayland.c @@ -22,6 +22,15 @@ * Jonas Ådahl */ +/** + * SECTION:meta-pointer-lock-wayland + * @title: MetaPointerLockWayland + * @short_description: A #MetaPointerConstraint implementing pointer lock. + * + * A MetaPointerLockConstraint implements the client pointer constraint "pointer + * lock": the cursor should not make any movement. + */ + #include "config.h" #include "wayland/meta-pointer-lock-wayland.h"