-/* This will write a snapshot of the screen image into the given window.
- Beware that the colormap of the window may also be changed (to match
- the bits that were drawn.)
+/* This will write an image onto the given Drawable.
+ The Drawable (arg 3) may be a Window or a Pixmap.
+
+ The Window must be the top-level window. The image *may or may not*
+ be written to the window, though it will definitely be written to
+ the drawable. It's fine for args 2 and 3 to be the same window, or
+ for arg 2 to be a Window, and arg 3 to be a Pixmap.
+
+ The loaded image might be from a file, or from a screen shot of the
+ desktop, or from the system's video input, depending on user
+ preferences.
+
+ If it is from a file, then it will be returned in `filename_return'.
+ filename_return may be NULL; also, NULL may be returned (e.g., if
+ it's a screenshot or video capture.) You are responsible for
+ freeing this string.
+
+ The size and position of the image is returned in `geometry_return'.
+ The image will generally have been scaled up to fit the window, but
+ if a loaded file had a different aspect ratio than the window, it
+ will have been centered, and the returned coords will describe that.
+
+ Many colors may be allocated from the window's colormap.