Starting with clutter 1.4 clutter / cogl only knows whether TFP is in use after
setting the pixmap, so doing the check before setting the pixmap will just
lead to a wrong message.
https://bugzilla.gnome.org/show_bug.cgi?id=624757
The current effect API passes an unnecessary list of windows to
switch_workspace() and forces a window to be passed in when killing
the switch_workspace() effect.
We can simplify the interface to correspond more closely to how
it is actually used and fix these problems:
Remove the actors parameter to plugin->switch_workspace
Remove the events parameter to plugin->kill_effect and rename it to kill_window_effects
Add plugin->kill_switch_workspace
Remove mutter_plugin_manager_kill_effect
Add mutter_plugin_manager_kill_window_effects
Add mutter_plugin_manager_kill_switch_workspace
Remove mutter_plugin_effect_completed
Add mutter_plugin_[minimize/map/destroy/maximize/unmaximize]_completed
https://bugzilla.gnome.org/show_bug.cgi?id=621082
In commit d34ae764769 I switched mutter-window to ask for Raw rectangles
from the X server. This avoided 2 non synchronous and 2 synchronous X
requests per window with damage, per frame; 2 (non-sync) to
create/destroy a temporary region to copy the damage region into, 1 to
request the server to copy the damage region into a our given region and
another to fetch that region back into the client. The problem with raw
events though is that it's possible to DOS the compositor with them.
Instead of receiving an event for every bit of damage this patch instead
asks the server to only report BoundingBox changes to the damage region.
https://bugzilla.gnome.org/show_bug.cgi?id=611838
COGL bug http://bugzilla.openedhand.com/show_bug.cgi?id=2110 results
in pending drawing at the time of cogl_offscreen_new_to_texture() going
to the newly created framebuffer rather than the stage.
This would result in most windows being missing for the first frame
when a new window is mapped.
Work around this by calling cogl_flush() before
cogl_offscreen_new_to_texture().
https://bugzilla.gnome.org/show_bug.cgi?id=618138
The beginning maximization/unmaximization don't go through
start_effect_simple(), so we need to freeze the window
separately.
Change MutterWindow.freeze_count to a signed integer for
consistency with other counts, and so the logic for
checking for errors works properly.
https://bugzilla.gnome.org/show_bug.cgi?id=616546
This changes the way we handle Damage events so instead of getting an
event when the damage region of a pixmap becomes non-empty we now get
sent all damage rectangles and stream those all though to
ClutterX11TexturePixmap using clutter_x11_texture_pixmap_update_area()
For Clutter 1.2, ClutterGLXTexturePixmap was updated so that calls to
clutter_x11_texture_pixmap_update_area are now cheap (glXBindTexImageEXT
calls are now deferred until just before painting) and since
ClutterGLXTexturePixmap is now capable of queueing clipped redraws that
can result in only updating a sub-region of the stage during a repaint
cycle (and using glXCopySubBufferMESA to present the sub-region redraw
to the front buffer) this should improve performance and reduced power
consumption for a range of use cases. (For example viewing a website
that has animated adverts doesn't force the whole screen to be redrawn
for each frame of the advert)
Besides being able to take advantage of glXCopySubBuffer to only update
a small region of the stage the fact that this patch makes Mutter now
request RawRectangles from the X server means we no longer do a
synchronous X request for a complete Damage Region for every window
damaged each frame. This should also improve performance.
CLUTTER_PAINT=redraws can be used to visualize what parts of the stage
are redrawn and with this patch applied I can open a terminal and as I
type I see that only the damaged areas of the terminal are being
redrawn.
In the case where a mutter window is created for an X Window that is
already mapped then we weren't calling mutter_window_mark_for_repair and
so we weren't calling XCompositeNameWindowPixmap e.g. for menu windows.
This doesn't get noticed because as soon as some damage gets delivered
for such windows the pixmap will be named anyway, but if we were to
change how damage is handled this would result in broken menus.
We now call mutter_window_mark_for_repair in mutter_window_new when the
given Window is already mapped.
Although multi-screen support has not been tested and probably
doesn't fully work, the basic setup for multi-screen is that
we have the same list of plugins for all screens, but a different
instance of the plugins for each screen.
To allow plugins to do setup that is screen independent and needs
to occur early in the setup process, we identify a "default plugin
manager" and load (but not start) that plugin manager's plugins
immediately after we know our list of plugins.
That plugin manager is then reused for the first screen we open
and the plugins are started at that time. Separate plugin managers
are loaded and started for any other screens we open.
(A plugin could keep track of whether the screen-independent
setup has been done in a static variable, or it could do everything
in a way that is safe to do repeatedly.)
https://bugzilla.gnome.org/show_bug.cgi?id=615586
Rather than using the plugin objects constructed() method for doing
setup that requires the MetaScreen, add an explicit start() method
that is called after the screen is set.
The reason for this is that this allows plugin objects to be created
early before the bulk of Metacity setup, which then allows plugins
to affect how the setup happens. (For example, to change the way
that preferences are loaded.)
This is an incompatible change, since 'screen' is now not set in the
constructed method, so the plugin API version is bumped.
https://bugzilla.gnome.org/show_bug.cgi?id=615586
Since all windows are now MetaWindows as well as compositor
windows, there's no reason to keep a compositor-specific hash table
mapping from XID to MutterWindow.
This reduces complexity and removes a call to XQueryTree that could
potentially produce a BadWindow error if not error-trapped.
https://bugzilla.gnome.org/show_bug.cgi?id=613398
meta_compositor_process_event uses meta_error_trap_push/pop for
every event processed by meta_compositor_process_event which isn't needed
and can cause performance problems.
https://bugzilla.gnome.org/show_bug.cgi?id=613398
- Specify a minimum version of Clutter-1.2.0
- Remove conditionalizatin and always use Clutter-1.1 framebuffer
API rather than raw GL fbos
- Replace deprecated cogl_material/texture_unref() with
cogl_handle_unref()
https://bugzilla.gnome.org/show_bug.cgi?id=610862
The older code relied on Clutter providing default texture coords for any
layers for which texture coords were not specified, which does not work as
of Clutter 1.1.6 (due to commit 8b950bdc87).
https://bugzilla.gnome.org/show_bug.cgi?id=609657
The CGL_* defines in COGL were always meant to be private and should
have never been exposed in the first place. The API in COGL has been
updated to never require them starting from 1.1, but using the original
GL symbols has always been the intent of the API.
This commit removes the CGL_TEXTURE_RECTANGLE_ARB usage in favour of the
ARB-sanctioned GL_TEXTURE_RECTANGLE_ARB enumeration value.
Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
https://bugzilla.gnome.org/show_bug.cgi?id=607398
PFNGLACTIVETEXTUREPROC (a GL-1.2 addition) was inadvertently missing
from some recent versions of Mesa (like that in Fedora 11.) Use
the identical PFNGLACTIVETEXTUREARBPROC instead.
the mutlitexture and texture_rectangle extensions have recently
been incorporated into the GL core; fixes needed to work with
libGL that proceeds that:
GL_TEXTURE_RECTANGLE_ARB - use _ARB name
glActiveTextureARB() - use get_proc_address
https://bugzilla.gnome.org/show_bug.cgi?id=602870
Add MutterTextureTower, an abstraction for getting a image with
the right level of detail for rendering at a particular scale,
by manually scaling down by powers of two.
This results in much better looking scaled window images when
mipmaps can't be used with texture_from_pixmap (which is the
typical case for current GL drivers.)
When framebuffer objects are available, they are used to do
the scaledown using the GPU without having to pull the data
back from video memory. A software codepath is also available
for the case when FBO's are not present, though performance
will suffer
https://bugzilla.gnome.org/show_bug.cgi?id=601032
The return value of XGrabKeyboard() wasn't actually being assigned
to the 'result' variable so we didn't notice when grabbing the
keyboard failed.
https://bugzilla.gnome.org/show_bug.cgi?id=596343
mutter_plugin_begin_modal() and mutter_plugin_begin_modal() allow putting
a plugin into a "modal" state. This means:
- The plugin has the keyboard and mouse grabbed
- All keyboard and mouse events go exclusively to the plugin
mutter-plugin.[ch]: Add public API
compositor.c compositor-private.h: Implement the API
mutter-plugin-manager.c: When reloading plugins, make sure none of them
are modal at that moment, and if so force-unmodal them.
common.h: Add META_GRAB_OP_COMPOSITOR
display: When display->grab_op is META_GRAB_OP_COMPOSITOR forward relevant
events exclusively to the compositor.
http://bugzilla.gnome.org/show_bug.cgi?id=590754
mutter-window.c originally grew an #include "window-private.h" for
window->override_redirect, but that was just fixed. However since
then it also ended up relying on a few other minor private bits.
To fix that, add meta_window_is_mapped, promote meta_window_toplevel_is_mapped
to public, and use the public MetaDisplay accessor.
When we first start up, we do not want to run effects on any pre-exising
windows (this is either the case we are starting up and there are no windows,
or we are replacing an exisint window manager, or worse, we crashed, and we
just want to get to the desired desktop as quick as possible).
Dithered about where to place the check; putting into the plugin manager
reduces the number of places (and files) in which it needs to be done.
We store a pointer to the texture independently of the ClutterContainer
internals, and rely on the pointer remaining valid until we run dispose.
Since we also provide public API to access this pointer, we should not
rely on the reference ClutterContainer holds to ensure that texture will
not be destroyed (e.g., some nasty developer could reparent the texture).
We were freeing the description string in dispose and not setting it to NULL,
thus leaving around a dangling pointer for the duration of the disposal.
This commit moves the free into the finalize vfuction, where it belongs.
Setting the size of the texture causes the minimum and preferred width and
height values to be fixed at the set value. The normal requisition functions
of ClutterTexture will already report the size of the texture pixmap as the
natural size, but also allow scaling down as needed if less space is
available. We don't need that here, but we want to allow someone to make
a ClutterClone of the texture actor.
With recent changes, Clutter no longer sets up the viewport correctly,
unless it receives ConfigureNotify events. If there is a plugin with
an xevent_filter function, then it's that plugins responsibility to pass
the event to Clutter if it doesn't want it. If there is no plugin,
or the plugin doesn't have an xevent_filter function, then we should
call clutter_x11_handle_event() ourselves.
http://bugzilla.gnome.org/show_bug.cgi?id=589419
When a windows contents or shape changes, we schedule a redraw
with clutter_actor_queue_redraw(); we need to queue the redraw
on the shaped texture rather than on the window actor to support
cloning of just the shaped texture without the shadow: that
is, the shaped is what is really changing and it may be
visible via a clone even if the MutterWindow itself is not
visible.
http://bugzilla.gnome.org/show_bug.cgi?id=589429
When we are painting a stack of 5-10 maximized windows, the
standard bottom-to-top method of drawing every actor results
in a tremendous amount of overdraw and can easily max out
the available memory bandwidth on a low-end* graphics chipset.
It's even worse if window textures are being accessed over
the AGP bus.
When we have opaque windows, we can go ahead and compute visibility
ourselves (in classic X-server fashion) and use that information to
restrict drawing obscured actors.
* Add MutterWindowGroup - a ClutterGroup subclass with logic
for figuring out obscured regions.
* Add mutter_window_get_obscured_region() to get the region
obscured by that window.
* Add mutter_shaped_texture_set_clip_region() to hint
a clip region to the painting code; this is set based on
the computed visible region of MutterWindowGroup.
* Add tidy_texture_frame_set_needs_paint() to hint that the
paint can be skipped entirely; this is used when we detect
that the window shadow is entirely obscured.
http://bugzilla.gnome.org/show_bug.cgi?id=587344
If we are starting on something other than the first workspace,
meta_compositor_switch_workspace() will be called before
meta_compositor_manage_screen(); guard against that.
Previously, changes to the visibility of a window could be indicated
by meta_compositor_map_window(), meta_compositor_unminimize_window(),
meta_compositor_set_window_hidden(), etc, with the exact behavior
depending on the 'live_hidden_windows' preference.
Simplify this so that visibility is controlled by:
meta_compositor_show_window()
meta_compositor_hide_window()
With an 'effect' parameter provided to indicate the appropriate
effect (CREATE/UNMINIMIZE/MINIMIZE/DESTROY/NONE.)
The map state of the window is signalled separately by:
meta_compositor_map_window()
meta_compositor_unmap_window()
And is used only to control resource handling.
Other changes:
* The desired effect on show/hide is explicitly stored in
MetaWindow, avoiding the need for the was_minimized flag.
At idle, once we calculate the window state, we pass the
effect to the compositor if it matches the new window
state, and then clear the effect to start over for future
map state changes.
* meta_compositor_switch_workspace() is called before any windows
are hidden or shown, allowing the compositor to avoid hiding
or showing an effect for windows involved in the switch.
http://bugzilla.gnome.org/show_bug.cgi?id=582341
* Handling of post-effect cleanups for MutterWindow are
simplified - instead of trying to do different things based
on the individual needs of different effects, we just wait until
all effects complete and sync the window state to what it
should be.
* On unmap, once we destroy the pixmap, we tell ClutterX11Pixmap
that we've done so, so it can clean up and unbind. (The
unbinding doesn't seem to be working properly because of
ClutterGLXPixmap or video driver issues.)
http://bugzilla.gnome.org/show_bug.cgi?id=587251
Clean up mutter_window_effect_in_progress() by removing the
include_destroy parameter which was used only in one place that
could be easily done otherwise. (There was another use in
mutter_window_sync_actor_position() that had no point and looked
unintended.)
http://bugzilla.gnome.org/show_bug.cgi?id=587251
Add a paint function that checks all windows for repair and
shape updates; this:
- simplifies the logic for when a window needs to be repaired
- avoids duplicate work when we get multiple damage effects
- avoids the need to look ahead in the event queue
Instead of relying on repair to implicitly resize the
MutterWindow actor, set the size explicitly when the core
code updates the geometry. (This is needed because we haven't
repaired yet when we start an animation, and the animation
may depend on the size to, e.g., rescale from the center.)
Because the core geometry update happens before we start
maximize/unmaximize effects we need to work around this by
passing both the old and new geometry to the compositor.
http://bugzilla.gnome.org/show_bug.cgi?id=587251
compositor.c: Move MutterWindow code to mutter-window.c;
rename map_win() to mutter_window_map(), etc.
mutter-window-private.h: New private header file for
MutterWindow functions used internally to the compositor.
compositor-mutter.h: Move MutterWindow declarations to
mutter-window.h; move a couple of private functions to
compositor-private.h
compositor-private.h: Move MetaCompScreen declaration to here:
Conceptually it's private to compositor.c, but MutterWindow
manipulates some of the lists directly for now.
mutter-plugin.c compositor.c: Don't call mutter_window_effect_completed()
for MUTTER_PLUGIN_SWITCH_WORKSPACE, but use a new
mutter_switch_workspace_completed(), since the window is
just used to identify a screen.
http://bugzilla.gnome.org/show_bug.cgi?id=587251
Separate code related to creating the gaussian-blurred shadow texture
into a separate file.
Move the definition of MetaCompositor into a compositor-private.h
so that the shadow code can cache the source in the compositor
structure.
http://bugzilla.gnome.org/show_bug.cgi?id=587251
Remove a number of functions that were either entirely unimplemented
or had empty implementations for the Clutter-compositor.
meta_compositor_begin_move()
meta_compositor_update_move()
meta_compositor_end_move()
meta_compositor_set_active_window()
meta_compositor_free_window()
http://bugzilla.gnome.org/show_bug.cgi?id=581813
Now that we only have one compositor, there's no reason to access the
compositor functions through a vtable. Remove the MetaCompositor virtualization
and make the clutter code implement the meta_compositor_* functions
directly.
Move the checks for the compositor being NULL from the vtable wrappers
to the calling code (most of them were already there, so just a few
needed to be added)
Note: the compositor is actually hard-coded on at the moment and the plan
is to remove the non-composited code entirely, so the checks are
added only to keep things neat: they have no practical effect.
http://bugzilla.gnome.org/show_bug.cgi?id=581813
Mutter is a Clutter-based compositing manager. So, remove the code for
the XRender-based compositor, and make it mandatory to have XComposite,
XRender and Clutter.
Run-time support for non-composited operation is left for now.
* src/compositor/mutter/: Move files from this subdirectory into
the main compositor/ directory.
* compositor/compositor-xrender.ccompositor/compositor-xrender.h:
Remove
* include/compositor-clutter.h: Remove this stray file, it had been
replaced with compositor-mutter.h some time back.
http://bugzilla.gnome.org/show_bug.cgi?id=581813
Since the stack passed to the compositor now accurately reflects
the X stacking order, we need to treat hidden windows (which are
at the bottom of the X stacking order) specially - when the
compositor stacking order is synced, try to keep animating hidden
actors in their old positions in the stack.
http://bugzilla.gnome.org/show_bug.cgi?id=585984
This reverts commit 16d49695ad.
If we want an actor to go away deterministically, we should call
clutter_actor_destroy(); using unparent instead a) may result
leaks through cyclic ref counts, and b) will delay the deallocation
of the window texture in a garbage collected environment until
the next garbage collection, causing much greater transient use
of memory.
http://bugzilla.gnome.org/show_bug.cgi?id=580520
info->pending_input_region needed to be destroyed in
mutter_set_stage_input_region() before it was set to something
else or before it was reset to be full screen (region == None).
Set the initial input area to an empty region by
setting info->pending_input_region to an empty region by default
and setting it to None or a new region if a new input region is
specified.
Remove show_overlay_window() function that was used to set an empty
input region on start-up, and uses a call to do_set_stage_input_region()
with info->pending_input_region as an argument instead.
Code:
All references in the code not related to themes, keybindings, or
GConf were changed from 'metacity' to 'mutter'. This includes, among other
things, strings, comments, the atoms used in the message protocol, and
the envvars used for debugging. The GConf schema file was reduced to
the 3 settings new to mutter.
The overall version was brought up to 2.27 to match current gnome.
Structure:
All files named '*metacity*' were renamed '*mutter*' with appropriate
changes in the automake system. Files removed are
doc/creating_themes, src/themes, doc/metacity-theme.dtd,
metacity.doap. These files will eventually end up in an external
gnome-wm-data module.
Installation location:
On the filesystem the mutter-plugindir was change from
$(libdir)/metacity/plugins/clutter to just $(libdir)/mutter/plugins.
The mutter-plugins.pc.in reflects these changes.
Note:
mutter.desktop.in and mutter-wm.desktop both continue to have
X-GNOME-WMSettingsModule=metacity set. This allows
gnome-control-center to continue using libmetacity.so for
configuration. This is fine since most the general keybindings and wm
settings are being read from /apps/metacity/* in gconf.
Change #define _XOPEN_SOURCE 500 to 600 in compositor-xrender.c to
avoid a bad interaction with -xc99 on Solaris.
Remove unneeded #define in compositor-mutter.c.
Based on a patch by Brian Cameron
http://bugzilla.gnome.org/show_bug.cgi?id=580662
Cogl's default blend function has been switched to expect premultiplied
alpha. Change the combine function and the colors we use to
modulate alpha to match.
http://bugzilla.gnome.org/show_bug.cgi?id=585480
It doesn't make sense to allow the window texture to be sliced,
but not allow the mask texture to be sliced. So, we should either
set 'disable-slicing' for the texture actor or not pass NO_SLICING when
creating the mask texture.
While slicing currently results in only the first layer being shown,
disabling slicing entirely would break windows larger than the texture
size limit. It would be straightforward to support multitexturing of
sliced textures in Cogl when all the textures are identically sized
and sliced identically, if it became a priority.
http://bugzilla.gnome.org/show_bug.cgi?id=585151
- Use float instead of ClutterUnit
- clutter_actor_get_size/position() return floats (remove some
stray usage of these functions in the default plugin as well.)
- Adapt to cogl_texture_new_from_data() changes
- Use blend strings to set up multitexturing
- Remove CLUTTER_UNITS_TO_FLOAT() usage
http://bugzilla.gnome.org/show_bug.cgi?id=585016
If the input region has been shaped, then clutter needs to
receive EnterNotify/LeaveNotify events in order to properly
send enter and leave events to actors when the pointer crosses
the boundary of the stage.
http://bugzilla.gnome.org/show_bug.cgi?id=578250
If mutter_plugin_set_stage_input_region() and related methods are
called before the output window is available, save the set input
region and apply it to the output window later on.
compository-mutter.[ch]: Add mutter_set_stage_input_region() and
mutter_empty_stage_input_region(), move the input region handling
here and implement the delayed shape setting described
above.
mutter-plugin.c: Implement shape setting in terms of the new methods.
http://bugzilla.gnome.org/show_bug.cgi?id=580042
Using G_MODULE_BIND_LOCAL causes problems for introspecting plugins,
since introspected symbols need to be globally available. And in
any case, trying to use linker features to prevent symbol conflicts
doesn't usually work out very well, it's better to just namespace
properly.
http://bugzilla.gnome.org/show_bug.cgi?id=580033
Add separate mutter_plugin_manager_load() and
mutter_plugin_manager_initialize() calls so that we can just
load the plugins without start them. This is useful for introspecting
a gnome-shell plugin at build time.
http://bugzilla.gnome.org/show_bug.cgi?id=580032
To guard against CompositeNameWindowPixmap failing, just use an
error trap. Previous code used:
GrabServer/GetWindowAttributes/CompositeNameWindowPixmap/UngrabServer
To prevent BadMatch errors from !viewable, but didn't check the
return value of GetWindowAttributes and didn't check if an error
occured during the error trap. This way is more correct and more
efficient.
http://bugzilla.gnome.org/show_bug.cgi?id=580023
The overlay window was created before the plugins are loaded. Because the
composite extension immediately maps the window, we ended blanking the screen
while plugins, etc., were loading. This commit reorganizes the code so that
the overlay window is only created just before we are ready to show the
stage.
The significant impact of this change is that plugins cannot manipulate the
overlay window during their initial loading, i.e., they cannot call the
input-region API (the plugin should hook into the "show" signal if it needs
to do anything of this sort).
The commit also removes the XClearArea() call on the overlay window that
seems to have served no real purpose.
Once the window destruction is initiated, we can still manipulate our
MutterWindow with clutter API, but we can not longer use any X-based API,
or MetaWindow API to query it.
Add 'hide_after_effect' flag to MutterWindowPrivate, tracking
whether the window needs to be hidden after all outstanding effects
finish.
Set or clear the flag as appropriate in clutter_cmp_set_window_hidden.
In mutter_window_effect_completed, if hide_after_effect is TRUE
and no other effects are in progress, hide the window.
Requiring the compositor private object to be a GObject allows the
return value of meta_window_get_compositor_private() to be used
via gobject-introspection, since the type and memory management
can be determined.
This allows a reverse mapping from MetaWindow to MutterWindow.
- Change meta_window_get/set_compositor_private to use GObject
rather than void *
- Adapt code in compositor-mutter.c to match.
Now that Cogl has the material API we can use Cogl calls for
multi-texturing instead of directly calling GL.
The MutterShapedTexture actor keeps a handle to a material with the
right combine modes for combining the texture and the shape
mask. Before each paint it sets the layers of the material to be the
two textures.
A second material with different combine modes 1is also created if the
pixmap is 24 bit to implement the workaround from commit 72da8c57.
It seems that with the latest intel drivers when multi-texturing using an RGB
TFP texture, the texture is being setup internally as an RGBA texture, where
the alpha channel is mostly 0.0 so you only see a shimmer of the window. This
workaround forcibly defines the alpha channel as 1.0. Maybe there is some
clutter/cogl state that is interacting with this that is being overlooked,
but for now this seems to work. (Tested on i945 + DRI2)
The addition of method implementations in the base class in the
plugin-gobject branch broke the logic for checking to see
if a plugin didn't implement an effect. Requiring a mandatory
chain up to the base class is a fiddly anyways, so this patch
does the 'running' count computations in a different (and more
robust) way.
mutter-plugin.h mutter-plugin.c: Add _mutter_plugin_effect_started()
to increment the running count.
mutter-plugin-manager.c: Call _mutter_plugin_effect_started()
as necessary.
mutter-plugin.c: Remove the "real" methods that did nothing
but implement the runnning count.
plugins/default.c: Remove chain-ups.
Fix a problem where GTK+ was warning
'gdk_window_set_user_time called on non-toplevel' for every button
press and click on the mutter stage by excluding such events from
GTK+ processing.
Add a boolean return value to meta_compositor_process_event that
indicates whether the event has been handled and should be filtered
out of the event stream and for mutter, base that on the return
value of the plugin's xevent_filter vfunc.
Before we've retrieved a pixmap for a window, the shaped texture
has a 0x0 texture, which will cause mutter_shaped_texture_ensure_mask()
to crash. Just skip all of paint/pick in this case.
http://bugzilla.openedhand.com/show_bug.cgi?id=1283
Add (transfer none) annotations to mutter_window_get_texture()
and mutter_window_get_meta_window(), and while add doc comments,
actually add some docs as well.
