


XmGetPixmapByDepth(3X)				       XmGetPixmapByDepth(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmGGeettPPiixxmmaappBByyDDeepptthh - A pixmap	caching	function that generates	a pixmap,
  stores it in a pixmap	cache, and returns the pixmap

SYNOPSIS


  ##iinncclluuddee <<XXmm//XXmm..hh>>
  PPiixxmmaapp XXmmGGeettPPiixxmmaappBByyDDeepptthh ((_s_c_r_e_e_n, _i_m_a_g_e__n_a_m_e,_f_o_r_e_g_r_o_u_n_d,
	  _b_a_c_k_g_r_o_u_n_d, _d_e_p_t_h))
       SSccrreeeenn	 **_s_c_r_e_e_n;;
       cchhaarr	 **_i_m_a_g_e__n_a_m_e;;
       PPiixxeell	 _f_o_r_e_g_r_o_u_n_d;;
       PPiixxeell	 _b_a_c_k_g_r_o_u_n_d;;
       iinntt	 _d_e_p_t_h;;

DESCRIPTION
  XXmmGGeettPPiixxmmaappBByyDDeepptthh uses the parameter	data to	perform	a lookup in the	pix-
  map cache to see if a	pixmap has already been	generated that matches the
  data.	 If one	is found, a reference count is incremented and the pixmap is
  returned.  Applications should use XXmmDDeessttrrooyyPPiixxmmaapp when the pixmap is	no
  longer needed.

  If a matching	pixmap is not found, _i_m_a_g_e__n_a_m_e	is used	to perform a lookup
  in the image cache.  If an image is found, it	is used	to generate the	pix-
  map, which is	then cached and	returned.

  If an	image is not found, _i_m_a_g_e__n_a_m_e is used as a filename, and a search is
  made for an XX1100 or XX1111 bitmap	file.  If it is	found, the file	is read, con-
  verted into an image,	and cached in the image	cache.	The image is then
  used to generate a pixmap, which is cached and returned.

  If _i_m_a_g_e__n_a_m_e	has a leading slash (//), it specifies a	full pathname, and
  XXmmGGeettPPiixxmmaappBByyDDeepptthh opens the file as specified.  Otherwise, _i_m_a_g_e__n_a_m_e
  specifies a filename.	 In this case XXmmGGeettPPiixxmmaappBByyDDeepptthh looks for the file
  along	a search path specified	by the XXBBMMLLAANNGGPPAATTHH environment variable	or by
  a default search path, which varies depending	on whether or not the XXAAPP--
  PPLLRREESSDDIIRR environment variable	is set.

  The XXBBMMLLAANNGGPPAATTHH environment variable specifies a search path for X bitmap
  files.  It can contain the substitution field	%B, where the _i_m_a_g_e__n_a_m_e
  argument to XXmmGGeettPPiixxmmaappBByyDDeepptthh is substituted	for %B.	 It can	also contain
  the substitution fields accepted by XXttRReessoollvveePPaatthhnnaammee.  The substitution
  field	%T is always mapped to bbiittmmaappss,	and %S is always mapped	to NULL.

  If XXBBMMLLAANNGGPPAATTHH is not	set, but the environment variable XXAAPPPPLLRREESSDDIIRR is set,
  the following	pathnames are searched:

		 %%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
		 //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

  If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set, the following pathnames are
  searched:

		 %%BB
		 $$HHOOMMEE//%%LL//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//%%ll//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//%%LL//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%ll//bbiittmmaappss//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
		 //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

  These	paths are defaults that	vendors	may change.  For example, a vendor
  may use different directories	for //uussrr//lliibb//XX1111 and //uussrr//iinncclluuddee//XX1111.

  The following	substitutions are used in these	paths:

  %%BB   The image name, from the	_i_m_a_g_e__n_a_m_e argument

  %%NN   The class name of the application

  %%LL   The display's language string

  %%ll   The language component of the display's language	string

  Parameter descriptions are listed below:

  _s_c_r_e_e_n    Specifies the display screen on which the pixmap is	to be drawn

  _i_m_a_g_e__n_a_m_e
	    Specifies the name of the image to be used to generate the pixmap

  _f_o_r_e_g_r_o_u_n_d
	    Combines the image with the	_f_o_r_e_g_r_o_u_n_d color to create the pixmap
	    if the image referenced is a bit-per-pixel image

  _b_a_c_k_g_r_o_u_n_d
	    Combines the image with the	_b_a_c_k_g_r_o_u_n_d color to create the pixmap
	    if the image referenced is a bit-per-pixel image

  _d_e_p_t_h	    Specifies the depth	of the pixmap

RETURN VALUE
  Returns a pixmap when	successful; returns XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP if the	image
  corresponding	to _i_m_a_g_e__n_a_m_e cannot be	found.

RELATED	INFORMATION
  XXmmDDeessttrrooyyPPiixxmmaapp((33XX)), XXmmIInnssttaallllIImmaaggee((33XX)), and XXmmUUnniinnssttaallllIImmaaggee((33XX)).




