git.hungrycats.org Git - xscreensaver/blob - hacks/glx/grab-ximage.h

   1 /* grab-ximage.c --- grab the screen to an XImage for use with OpenGL.
   2  * xscreensaver, Copyright (c) 2001-2005 Jamie Zawinski <jwz@jwz.org>
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and its
   5  * documentation for any purpose is hereby granted without fee, provided that
   6  * the above copyright notice appear in all copies and that both that
   7  * copyright notice and this permission notice appear in supporting
   8  * documentation.  No representations are made about the suitability of this
   9  * software for any purpose.  It is provided "as is" without express or
  10  * implied warranty.
  11  */
  12
  13 #ifndef __GRAB_XIMAGE_H__
  14 #define __GRAB_XIMAGE_H__
  15
  16 /* Grabs an image of the desktop (or another random image file) and
  17    loads tht image into GL's texture memory.
  18
  19    As a side-effect, that image *may* be painted onto the given Window.
  20
  21    If mipmap_p is true, then make mipmaps instead of just a single texture.
  22
  23    If desired_width/height are non-zero, then (if possible) the image
  24    will be scaled to fit in that rectangle.  If they are 0, then the size
  25    of the window is used.  These parameters are so that you can hint to
  26    the image loader that smaller images are acceptable (if you will never
  27    be displaying the texture at 100% magnification, you can get away with
  28    smaller textures.)
  29
  30    Returns the sizes of various things:
  31
  32       texture_width/height: The size of the texture itself, in pixels.
  33                             This will often be larger than the grabbed
  34                             image, since OpenGL sometimes requires texture
  35                             dimensions to be a power of 2.
  36
  37       image_width/height:   The size of the image: this will usually be the
  38                             same as the desired_width/height you passed in
  39                             (but may be the size of the Window instead.)
  40
  41       geometry:             The position in the texture of the image bits.
  42                             When image files are loaded, they are scaled up
  43                             to the size of the window, but if the image does
  44                             not have the same aspect ratio as the window,
  45                             there will be black bars on the top/bottom or
  46                             left/right.  This geometry specification tells
  47                             you where the "real" image bits are.
  48
  49    So, don't use texture coordinates from 0.0 to 1.0.  Instead use:
  50
  51       [0.0 - iw/tw]         If you want to display a quad that is the same
  52       [0.0 - ih/th]         size as the window; or
  53
  54       [gx/tw - (gx+gw)/tw]  If you want to display a quad that is the same
  55       [gy/th - (gy+gh)/th]  size as the loaded image file.
  56
  57    Writes to stderr and returns False on error.
  58  */
  59 Bool screen_to_texture (Screen *screen, Window window,
  60                         int desired_width, int desired_height,
  61                         Bool mipmap_p,
  62                         char **filename_return,
  63                         XRectangle *geometry_return,
  64                         int *image_width_return,
  65                         int *image_height_return,
  66                         int *texture_width_return,
  67                         int *texture_height_return);
  68
  69
  70 /* Like the above, but the image is loaded in a background process,
  71    and a callback is run when the loading is complete.
  72    When the callback is called, the image data will have been loaded
  73    into texture number `texid' (via glBindTexture.)
  74
  75    If an error occurred, width/height will be 0.
  76  */
  77 void screen_to_texture_async (Screen *screen, Window window,
  78                               int desired_width, int desired_height,
  79                               Bool mipmap_p,
  80                               GLuint texid,
  81                               void (*callback) (const char *filename,
  82                                                 XRectangle *geometry,
  83                                                 int image_width,
  84                                                 int image_height,
  85                                                 int texture_width,
  86                                                 int texture_height,
  87                                                 void *closure),
  88                               void *closure);
  89
  90 #endif /* __GRAB_XIMAGE_H__ */