[0m


XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



[1mNAME
     [0mxloadimage, xsetbg, xview - load images into an X11 window
     or onto the root window

[1mSYNOPSIS
     [0m_x_l_o_a_d_i_m_a_g_e [global_options] {[image_options] image ...}

[1mDESCRIPTION
     [0m_X_l_o_a_d_i_m_a_g_e displays images in an X11 window or loads them
     onto the root window.  See the _I_M_A_G_E _T_Y_P_E_S section below for
     supported image types.

     If the destination display cannot support the number of
     colors in the image, the image will be dithered (monochrome
     destination) or have its colormap reduced (color destina-
     tion) as appropriate.  This can also be done forcibly with
     the -_h_a_l_f_t_o_n_e and -_c_o_l_o_r_s options.

     If more than one image is to be loaded, they will be merged
     into a single image.  The -_a_t and -_c_e_n_t_e_r options control
     where subsequent images will be loaded onto the initial
     image.  Any combination of color image depths and/or mono-
     chrome images may be loaded at one time.  If merging two
     color images would overload the number of available colormap
     entries, the number of colors shared between the images will
     be automatically reduced to fit.

     A variety of image manipulations can be specified, including
     brightening, clipping, dithering, depth-reduction, and zoom-
     ing.  Most of these manipulations have simple implementa-
     tions; speed was opted for above accuracy.

     If you are viewing a large image in a window, the initial
     window will be at most 90% of the size of the display unless
     the window manager does not correctly handle window size
     requests or if you've used the -_f_u_l_l_s_c_r_e_e_n option.  You may
     move the image around in the window by dragging with the
     first mouse button.  The cursor will indicate which direc-
     tions you may drag, if any.  You may exit the window by typ-
     ing 'q' or '^C' when the keyboard focus is on the window.

     It's possible to have a "slideshow" of many images by speci-
     fying the -_s_l_i_d_e_s_h_o_w option.

     A wide variety of common image manipulations can be done by
     mixing and matching the available options.  See the section
     entitled _H_I_N_T_S _F_O_R _G_O_O_D _I_M_A_G_E _D_I_S_P_L_A_Y_S for some ideas.

     _X_s_e_t_b_g is equivalent to _x_l_o_a_d_i_m_a_g_e -_o_n_r_o_o_t -_q_u_i_e_t and _x_v_i_e_w
     is equivalent to _x_l_o_a_d_i_m_a_g_e -_v_i_e_w -_v_e_r_b_o_s_e.





Printed 21/11/91	13 December 1989			1






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



[1mGLOBAL OPTIONS
     [0mThe following options affect the global operation of
     _x_l_o_a_d_i_m_a_g_e.  They may be specified anywhere on the command
     line.

     -border _c_o_l_o_r
	     This sets the background portion of the window which
	     is not covered by any images to be _c_o_l_o_r.

     -color  Use a color visual - normally _x_l_o_a_d_i_m_a_g_e uses the
	     default visual of the screen, specifying this option
	     forces it to look for a color (StaticColor, Pseu-
	     doColor, TrueColor or DirectColor) visual.  See also
	     -gray, -dynamic and -static.  If the search for the
	     desired visual fails _x_l_o_a_d_i_m_a_g_e will give up.

     -delay _s_e_c_o_n_d_s
	     Show each image one after the other, delaying
	     _s_e_c_o_n_d_s seconds between each image.  The effect is
	     the same as [1m-slideshow [0mexcept that the next image is
	     displayed automatically and the program redisplays
	     the first image after the last instead of exiting.

     -display _d_i_s_p_l_a_y__n_a_m_e
	     X11 display name to send the image(s) to.

     -dynamic
	     Use a dynamic visual (GrayScale, PseudoColor or
	     DirectColor).

     -fullscreen
	     Use the entire screen to display images.  This
	     option is incompatible with -onroot.

     -geometry _W_x_H[{+-_X}{+-}_Y]
	     This sets the size of the window onto which the
	     images are loaded to a different value than the size
	     of the image.  When viewing an image in a window,
	     this can be used to reduce the size of the destina-
	     tion window.  When loading an image onto the root
	     window, this option controls the size of the pixmap
	     which will be loaded onto the root.  If the size is
	     smaller than that of the display, the image will be
	     replicated.

     -gray   Use a black and white visual (StaticGray or GrayS-
	     cale).

     -install
	     Forcibly install the image's colormap when the win-
	     dow is focused.  This violates ICCCM standards and
	     only exists to allow operation with naive window



Printed 21/11/91	13 December 1989			2






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



	     managers.	Use this option only if your window
	     manager does not install colormaps properly.

     -list   List the images which are along the image path.

     -help   Displays a short summary of xloadimage command line
	     syntax.

     -onroot Load image(s) onto the root window instead of view-
	     ing in a window.  This is the opposite of -_v_i_e_w.
	     _X_S_e_t_b_g has this option set by default.  Loading with
	     the -onroot option will fail if enough sharable
	     colors cannot be allocated from the default color-
	     map.  This option also causes the visual used to be
	     the default visual of the screen - so it cannot be
	     combined with -color, -gray, -dynamic or -static.

     -path   Displays the image path and image suffixes which
	     will be used when looking for images.  These are
	     loaded from ~/.xloadimagerc and optionally from a
	     systemwide file (normally /usr/lib/xloadimagerc).

     -quiet  Forces _x_l_o_a_d_i_m_a_g_e and _x_v_i_e_w to be quiet.  This is
	     the default for _x_s_e_t_b_g, but the others like to whis-
	     tle.

     -slideshow
	     Show each image argument one at a time instead of
	     merging them.  Typing 'p' will back up to the previ-
	     ous image displayed, 'n' will go to the next image,
	     and 'q' or '^C' will quit.  This option is often
	     used in conjunction with -fullscreen.

     -static Use a static visual (StaticGray, StaticColor or
	     TrueColor).

     -supported
	     List the supported image types.

     -verbose
	     Causes _x_l_o_a_d_i_m_a_g_e to be talkative, telling you what
	     kind of image it's playing with and any special pro-
	     cessing that it has to do. This is the default for
	     _x_v_i_e_w and _x_l_o_a_d_i_m_a_g_e.

     -version
	     Print the version number and patchlevel of this ver-
	     sion of _x_l_o_a_d_i_m_a_g_e.  Versions prior to version 1,
	     patchlevel 03 do not have this option and should be
	     updated.

     -view   View image(s) in a window.  This is the opposite of



Printed 21/11/91	13 December 1989			3






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



	     -_o_n_r_o_o_t and the default for _x_s_e_t_b_g.

[1mIMAGE OPTIONS
     [0mThe following options may preceed each image.  These options
     are local to the image they preceed.

     -at _X,_Y
	  Indicates coordinates to load the image at on the first
	  image.  If this is an option to the first image, and
	  the -_o_n_r_o_o_t option is specified, the image will be
	  loaded at the given location on the display background.

     -background _c_o_l_o_r
	  Use _c_o_l_o_r as the background color instead of the
	  default (usually white but this depends on the image
	  type) if you are transferring a monochrome image to a
	  color display.

     -brighten _p_e_r_c_e_n_t_a_g_e
	  Specify a percentage multiplier for a color image's
	  colormap.  A value of more than 100 will brighten an
	  image, one of less than 100 will darken it.

     -center
	  Center the image on the first image loaded.  If this is
	  an option to the first image, and the -_o_n_r_o_o_t option is
	  specified, the image will be centered on the display
	  background.

     -colors _n
	  Specify the maximum number of colors to use in the
	  image.  This is a way to forcibly reduce the depth of
	  an image.

     -clip _X,_Y,_W,_H
	  Clip the image before loading it.  _X and _Y define the
	  upper-left corner of the clip area, and _W and _H define
	  the extents of the area.  A zero value for _W or _H will
	  be interpreted as the remainder of the image.

     -dither
	  Dither a color image to monochrome.  This algorithm is
	  very trivial; the -_h_a_l_f_t_o_n_e option may look better if
	  you don't mind the blown-up image.

     -foreground _c_o_l_o_r
	  Use _c_o_l_o_r as the foreground color instead of black if
	  you are transferring a monochrome image to a color
	  display.  This can also be used to invert the fore-
	  ground and background colors of a monochrome image.

     -halftone



Printed 21/11/91	13 December 1989			4






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



	  Force halftone dithering of a color image when display-
	  ing on a monochrome display.	This happens by default
	  when viewing color images on a monochrome display.
	  This option is ignored on monochrome images.	This
	  dithering algorithm blows an image up by sixteen times;
	  if you don't like this, the -_d_i_t_h_e_r option will not
	  blow the image up (but won't look as nice).

     -name _i_m_a_g_e__n_a_m_e
	  Force the next argument to be treated as an image name.
	  This is useful if the name of the image is -_d_i_t_h_e_r, for
	  instance.

     -xzoom _p_e_r_c_e_n_t_a_g_e
	  Zoom the X axis of an image by _p_e_r_c_e_n_t_a_g_e.  A number
	  greater than 100 will expand the image, one smaller
	  will compress it.  A zero value will be ignored.

     -yzoom _p_e_r_c_e_n_t_a_g_e
	  Zoom the Y axis of an image by _p_e_r_c_e_n_t_a_g_e.  See -_x_z_o_o_m
	  for more information.

     -zoom _p_e_r_c_e_n_t_a_g_e
	  Zoom both the X and Y axes by _p_e_r_c_e_n_t_a_g_e.  See -_x_z_o_o_m
	  for more information.  Technically the percentage actu-
	  ally zoomed is the square of the number supplied since
	  the zoom is to both axes, but I opted for consistency
	  instead of accuracy.

[1mEXAMPLES
     [0mTo load the rasterfile "my.image" onto the background and
     replicate it to fill the entire background:

	  xloadimage -onroot my.image

     To load a monochrome image "my.image" onto the background,
     using red as the foreground color, replicate the image, and
     overlay "another.image" onto it at coordinate (10,10):

	  xloadimage -foreground red my.image -at 10,10
     another.image

     To center the rectangular region from 10 to 110 along the X
     axis and from 10 to the height of the image along the Y
     axis:

	  xloadimage -center -clip 10,10,100,0 my.image

     To double the size of an image:

	  xloadimage -zoom 200 my.image




Printed 21/11/91	13 December 1989			5






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



     To halve the size of an image:

	  xloadimage -zoom 50 my.image

     To brighten a dark image:

	  xloadimage -brighten 150 my.image

     To darken a bright image:

	  xloadimage -brighten 50 my.image

[1mHINTS FOR GOOD IMAGE DISPLAYS
     [0mSince images are likely to come from a variety of sources,
     they may be in a variety of aspect ratios which may not be
     supported by your display.  The -_x_z_o_o_m and -_y_z_o_o_m options
     can be used to change the aspect ratio of an image before
     display.  If you use these options, it is recommended that
     you increase the size of one of the dimensions instead of
     shrinking the other, since shrinking looses detail.  For
     instance, many GIF images have an X:Y ratio of about 2:1.
     You can correct this for viewing on a 1:1 display with
     either -_x_z_o_o_m _5_0 or -_y_z_o_o_m _2_0_0 (reduce X axis to 50% of its
     size and expand Y axis to 200% of its size, respectively)
     but the latter should be used so no detail is lost in the
     conversion.

     When merging images, the first image loaded is used to
     determine the depth of the merged image.  This becomes a
     problem if the first image is monochrome and other images
     are color, since the other images will be dithered to mono-
     chrome before merging.  You can get around this behavior by
     using the -_g_e_o_m_e_t_r_y option to specify the size of the desti-
     nation image -- this will force _x_l_o_a_d_i_m_a_g_e to use the
     default depth of the display instead of 1.  The standard
     behavior might be modified in the future if it becomes a
     problem.

     You can perform image processing on a small portion of an
     image by loading the image more than once and using the -_a_t
     and -_c_l_i_p options.  Load the image, then load it again and
     clip, position, and process the second.  To brighten a
     100x100 rectangular portion of an image located at (50,50),
     for instance, you could type:

	  xloadimage my.image -at 50,50 -clip 50,50,100,100
     -brighten 150 my.image

     One common use of _x_l_o_a_d_i_m_a_g_e is to load images onto the root
     window.  Unfortunately there is no agreed-upon method of
     freeing some root window resources, such as colormap
     entries, nor is there a way to modify the root window



Printed 21/11/91	13 December 1989			6






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



     colormap without confusing most window managers.  For this
     reason, _x_l_o_a_d_i_m_a_g_e will not allow the loading of images onto
     the root window if it cannot allocate shared colors from the
     root window's colormap.  I suggest the avoidance of multiple
     color image loads onto the root window, as these eat up root
     window shareable colormap entries.  If you wish to have a
     slideshow, display the images in a window.  A future imple-
     mentation of _x_l_o_a_d_i_m_a_g_e will have a -_f_u_l_l_s_c_r_e_e_n (or maybe
     -_s_l_i_d_e_s_h_o_w) option, but this is as yet unavailable.

     One common complaint is that _x_l_o_a_d_i_m_a_g_e does not have a
     -_r_e_v_e_r_s_e function for inverting monochrome images.  In fact,
     this function is a special-case of the foreground and back-
     ground coloring options.  To invert an image with a black
     foreground and white background (which is standard), use
     -_f_o_r_e_g_r_o_u_n_d _w_h_i_t_e -_b_a_c_k_g_r_o_u_n_d _b_l_a_c_k.  This will work on both
     color and monochrome displays.

[1mPATHS AND EXTENSIONS
     [0mThe file ~/.xloadimagerc (and optionally a system-wide file)
     defines the path and default extensions that _x_l_o_a_d_i_m_a_g_e will
     use when looking for images.  This file can have two state-
     ments: "path=" and "extension=" (the equals signs must fol-
     low the word with no spaces between).  Everything following
     the "path=" keyword will be prepended to the supplied image
     name if the supplied name does not specify an existing file.
     The paths will be searched in the order they are specified.
     Everything following the "extension=" keyword will be
     appended to the supplied image name if the supplied name
     does not specify an existing file.  As with paths, these
     extensions will be searched in the order they are given.
     Comments are any portion of a line following a hash-mark
     (#).

     The following is a sample ~/.xloadimagerc file:

       # paths to look for images in
       path= /usr/local/images
	     /home/usr1/guest/madd/images
	     /usr/include/X11/bitmaps

       # default extensions for images; .Z is automatic; scanned in order
       extension= .csun .msun .sun .face .xbm .bm

     Versions of _x_l_o_a_d_i_m_a_g_e prior to version 01, patchlevel 03
     would load the system-wide file (if any), followed by the
     user's file.  This behavior made it difficult for the user
     to configure her environment if she didn't want the default.
     Newer versions will ignore the system-wide file if a per-
     sonal configuration file exists.





Printed 21/11/91	13 December 1989			7






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



[1mIMAGE TYPES
     [0m_X_l_o_a_d_i_m_a_g_e currently supports the following image types:

       Faces Project images
       GIF images
       Portable Bitmap (PBM) images
       Sun monochrome rasterfiles
       Sun color RGB rasterfiles
       X10 bitmap files
       X11 bitmap files
       X pixmap files

     Normal, compact, and raw PBM images are supported.  Both
     standard and run-length encoded Sun rasterfiles are sup-
     ported.  Any image whose name ends in .Z is assumed to be a
     compressed image and will be filtered through "uncompress".

[1mAUTHOR
     [0mJim Frost
     Saber Software
     jimf@saber.com

     Other contributing people include Barry Shein (bzs@std.com),
     Kirk Johnson (tuna@athena.mit.edu), Mark Snitily
     (zok!mark@apple.com), W. David Higgins
     (wdh@mkt.csd.harris.com), and Dave Nelson
     (daven@gauss.llnl.gov).

[1mFILES
     [0mxloadimage          The image loader and viewer.
     xsetbg		 Pseudonym which sets the background.
     xview		 Pseudonym which views in a window.
     /usr/lib/X11/app-defaults/Xloadimage
			 System-wide configuration file.
     $HOME/.xloadimagerc Personal configuration file.

[1mCOPYRIGHT
     [0mCopyright (c) 1989, 1990 Jim Frost and others.

     _X_l_o_a_d_i_m_a_g_e is copywritten material with a very loose copy-
     right allowing unlimited modification and distribution if
     the copyright notices are left intact.  Various portions are
     copywritten by various people, but all use a modification of
     the MIT copyright notice.	Please check the source for com-
     plete copyright information.  The intent is to keep the
     source free, not to stifle its distribution, so please write
     to me if you have any questions.

[1mBUGS
     [0mZooming dithered images, especially downwards, is UGLY.





Printed 21/11/91	13 December 1989			8






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



     The dithering algorithm used by -_d_i_t_h_e_r could be better, and
     both -_d_i_t_h_e_r and -_h_a_l_f_t_o_n_e assume that a color's brightness
     is the sum of its RGB values, which is not correct but has
     the advantage of being simple and fast.

     Images can come in a variety of aspect ratios.  _X_l_o_a_d_i_m_a_g_e
     cannot detect what aspect ratio the particular image being
     loaded has, nor the aspect ratio of the destination display,
     so images with differing aspect ratios from the destination
     display will appear distorted.  See _H_I_N_T_S _F_O_R _G_O_O_D _I_M_A_G_E
     _D_I_S_P_L_A_Y_S for more information.

     The GIF format allows more than one image to be stored in a
     single GIF file, but _x_l_o_a_d_i_m_a_g_e will only display the first.

     Only PseudoColor, GrayScale, StaticColor, and StaticGray
     visuals are supported.  These are the most common visuals so
     this isn't usually a problem.

     You cannot load an image onto the root window if the default
     visual is not supported by _x_l_o_a_d_i_m_a_g_e.

     Images loaded onto the root window are retained with
     XSetCloseDownMode(disp, RetainTemporary) so that they can be
     easily cleaned out by future image loads.	Any application
     that does an XKillClient(disp, AllTemporary) will free up
     the root colormap (and things will get ugly).  Likewise,
     xloadimage will free up resources which other applications
     have retained via RetainTemporary.

     One of the pseudonyms for _x_l_o_a_d_i_m_a_g_e, _x_v_i_e_w, is the same
     name as Sun uses for their SunView-under-X package.  This
     will be confusing if you're one of those poor souls who has
     to use Sun's XView.

     Some window managers do not correctly handle window size
     requests.	In particular, many versions of the twm window
     manager use the MaxSize hint instead of the PSize hint,
     causing images which are larger than the screen to display
     in a window larger than the screen, something which is nor-
     mally avoided.  Some versions of twm also ignore the MaxSize
     argument's real function, to limit the maximum size of the
     window, and allow the window to be resized larger than the
     image.  If this happens, _x_l_o_a_d_i_m_a_g_e merely places the image
     in the upper-left corner of the window and uses the zero-
     value'ed pixel for any space which is not covered by the
     image.  This behavior is less-than-graceful but so are win-
     dow managers which are cruel enough to ignore such details.

     The order in which operations are performed on an image is
     independent of the order in which they were specified on the
     command line.  Wherever possible I tried to order operations



Printed 21/11/91	13 December 1989			9






XLOADIMAGE(1)	    UNIX Programmer's Manual	    XLOADIMAGE(1)



     in such a way as to look the best possible (zooming before
     dithering, for instance) or to increase speed (zooming down-
     ward before compressing, for instance).

     Supplying random files (in particular image formats which
     the program does not understand) will cause _x_l_o_a_d_i_m_a_g_e to
     fail.
















































Printed 21/11/91	13 December 1989		       10



[0m