home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / x11r6.1 / man / cat3 / xallocstandardcolormap.0 < prev    next >
Encoding:
Text File  |  1996-10-17  |  9.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. XAllocStandardColormap(3X11X)LIB FUNCTIOXNASllocStandardColormap(3X11)
  5.  
  6.  
  7. NNAAMMEE
  8.        XAllocStandardColormap, XSetRGBColormaps, XGetRGBCol-
  9.        ormaps, XStandardColormap - allocate, set, or read a stan-
  10.        dard colormap structure
  11.  
  12. SSYYNNTTAAXX
  13.        XStandardColormap *XAllocStandardColormap()
  14.  
  15.        void XSetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d___c_o_l_o_r_m_a_p, _c_o_u_n_t,
  16.        _p_r_o_p_e_r_t_y)
  17.          Display *_d_i_s_p_l_a_y;
  18.          Window _w;
  19.          XStandardColormap *_s_t_d___c_o_l_o_r_m_a_p;
  20.          int _c_o_u_n_t;
  21.          Atom _p_r_o_p_e_r_t_y;
  22.  
  23.        Status XGetRGBColormaps(_d_i_s_p_l_a_y, _w, _s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n,
  24.        _c_o_u_n_t___r_e_t_u_r_n, _p_r_o_p_e_r_t_y)
  25.          Display *_d_i_s_p_l_a_y;
  26.          Window _w;
  27.          XStandardColormap **_s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n;
  28.          int *_c_o_u_n_t___r_e_t_u_r_n;
  29.          Atom _p_r_o_p_e_r_t_y;
  30.  
  31. AARRGGUUMMEENNTTSS
  32.        _d_i_s_p_l_a_y     Specifies the connection to the X server.
  33.  
  34.        _c_o_u_n_t     Specifies the number of colormaps.
  35.  
  36.        _c_o_u_n_t___r_e_t_u_r_n
  37.          Returns the number of colormaps.
  38.  
  39.        _p_r_o_p_e_r_t_y     Specifies the property name.
  40.  
  41.        _s_t_d___c_o_l_o_r_m_a_p
  42.          Specifies the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure to be
  43.          used.
  44.  
  45.        _s_t_d___c_o_l_o_r_m_a_p___r_e_t_u_r_n
  46.          Returns the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.
  47.  
  48. DDEESSCCRRIIPPTTIIOONN
  49.        The _X_A_l_l_o_c_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p function allocates and returns
  50.        a pointer to a _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure.  Note that all
  51.        fields in the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure are initially
  52.        set to zero.  If insufficient memory is available, _X_A_l_l_o_c_-
  53.        _S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p returns NULL.  To free the memory allo-
  54.        cated to this structure, use _X_F_r_e_e.
  55.  
  56.        The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function replaces the RGB colormap
  57.        definition in the specified property on the named window.
  58.        If the property does not already exist, _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s
  59.        sets the RGB colormap definition in the specified property
  60.        on the named window.  The property is stored with a type
  61.  
  62.  
  63.  
  64. X Version 11           Release 6.1                1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. XAllocStandardColormap(3X11X)LIB FUNCTIOXNASllocStandardColormap(3X11)
  71.  
  72.  
  73.        of RGB_COLOR_MAP and a format of 32.  Note that it is the
  74.        caller's responsibility to honor the ICCCM restriction
  75.        that only RGB_DEFAULT_MAP contain more than one defini-
  76.        tion.
  77.  
  78.        The _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s function usually is only used by win-
  79.        dow or session managers.     To create a standard colormap,
  80.        follow this procedure:
  81.  
  82.        1.   Open a new connection to the same server.
  83.  
  84.        2.   Grab the server.
  85.  
  86.        3.   See if the property is on the property list of the
  87.         root window for the screen.
  88.  
  89.        4.   If the desired property is not present:
  90.  
  91.         +o     Create a colormap (unless you are using the
  92.          default colormap of the screen).
  93.  
  94.         +o     Determine the color characteristics of the
  95.          visual.
  96.  
  97.         +o     Allocate cells in the colormap (or create it
  98.          with _A_l_l_o_c_A_l_l).
  99.  
  100.         +o     Call _X_S_t_o_r_e_C_o_l_o_r_s to store appropriate color
  101.          values in the colormap.
  102.  
  103.         +o     Fill in the descriptive members in the _X_S_t_a_n_-
  104.          _d_a_r_d_C_o_l_o_r_m_a_p structure.
  105.  
  106.         +o     Attach the property to the root window.
  107.  
  108.         +o     Use _X_S_e_t_C_l_o_s_e_D_o_w_n_M_o_d_e to make the resource per-
  109.          manent.
  110.  
  111.        5.   Ungrab the server.
  112.  
  113.        _X_S_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate _B_a_d_A_l_l_o_c, _B_a_d_A_t_o_m, and _B_a_d_-
  114.        _W_i_n_d_o_w errors.
  115.  
  116.        The _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s function returns the RGB colormap
  117.        definitions stored in the specified property on the named
  118.        window.    If the property exists, is of type RGB_COLOR_MAP,
  119.        is of format 32, and is long enough to contain a colormap
  120.        definition, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s allocates and fills in space
  121.        for the returned colormaps and returns a nonzero status.
  122.        If the visualid is not present, _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s assumes
  123.        the default visual for the screen on which the window is
  124.        located; if the killid is not present, _N_o_n_e is assumed,
  125.        which indicates that the resources cannot be released.
  126.        Otherwise, none of the fields are set, and
  127.  
  128.  
  129.  
  130. X Version 11           Release 6.1                2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. XAllocStandardColormap(3X11X)LIB FUNCTIOXNASllocStandardColormap(3X11)
  137.  
  138.  
  139.        _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s returns a zero status.    Note that it is
  140.        the caller's responsibility to honor the ICCCM restriction
  141.        that only RGB_DEFAULT_MAP contain more than one defini-
  142.        tion.
  143.  
  144.        _X_G_e_t_R_G_B_C_o_l_o_r_m_a_p_s can generate _B_a_d_A_t_o_m and _B_a_d_W_i_n_d_o_w
  145.        errors.
  146.  
  147. SSTTRRUUCCTTUURREESS
  148.        The _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p structure contains:
  149.  
  150.        /* Hints */
  151.        #define     _R_e_l_e_a_s_e_B_y_F_r_e_e_i_n_g_C_o_l_-    ( (XID)
  152.          _o_r_m_a_p            1L)
  153.        /* Values */
  154.        typedef struct {
  155.         Colormap colormap;
  156.         unsigned long red_max;
  157.         unsigned long red_mult;
  158.         unsigned long green_max;
  159.         unsigned long green_mult;
  160.         unsigned long blue_max;
  161.         unsigned long blue_mult;
  162.         unsigned long base_pixel;
  163.         VisualID visualid;
  164.         XID killid;
  165.        } XStandardColormap;
  166.  
  167.        The colormap member is the colormap created by the _X_C_r_e_-
  168.        _a_t_e_C_o_l_o_r_m_a_p function.  The red_max, green_max, and
  169.        blue_max members give the maximum red, green, and blue
  170.        values, respectively.  Each color coefficient ranges from
  171.        zero to its max, inclusive.  For example, a common col-
  172.        ormap allocation is 3/3/2 (3 planes for red, 3 planes for
  173.        green, and 2 planes for blue).  This colormap would have
  174.        red_max = 7, green_max = 7, and blue_max = 3.  An alter-
  175.        nate allocation that uses only 216 colors is red_max = 5,
  176.        green_max = 5, and blue_max = 5.
  177.  
  178.        The red_mult, green_mult, and blue_mult members give the
  179.        scale factors used to compose a full pixel value.  (See
  180.        the discussion of the base_pixel members for further
  181.        information.)  For a 3/3/2 allocation, red_mult might be
  182.        32, green_mult might be 4, and blue_mult might be 1.  For
  183.        a 6-colors-each allocation, red_mult might be 36,
  184.        green_mult might be 6, and blue_mult might be 1.
  185.  
  186.        The base_pixel member gives the base pixel value used to
  187.        compose a full pixel value.  Usually, the base_pixel is
  188.        obtained from a call to the _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s function.
  189.        Given integer red, green, and blue coefficients in their
  190.        appropriate ranges, one then can compute a corresponding
  191.        pixel value by using the following expression:
  192.  
  193.  
  194.  
  195.  
  196. X Version 11           Release 6.1                3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. XAllocStandardColormap(3X11X)LIB FUNCTIOXNASllocStandardColormap(3X11)
  203.  
  204.  
  205.        (r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
  206.  
  207.        For _G_r_a_y_S_c_a_l_e colormaps, only the colormap, red_max,
  208.        red_mult, and base_pixel members are defined.  The other
  209.        members are ignored.  To compute a _G_r_a_y_S_c_a_l_e pixel value,
  210.        use the following expression:
  211.  
  212.        (gray * red_mult + base_pixel) & 0xFFFFFFFF
  213.  
  214.        Negative multipliers can be represented by converting the
  215.        2's complement representation of the multiplier into an
  216.        unsigned long and storing the result in the appropriate
  217.        _mult field.  The step of masking by 0xFFFFFFFF effec-
  218.        tively converts the resulting positive multiplier into a
  219.        negative one.  The masking step will take place automati-
  220.        cally on many machine architectures, depending on the size
  221.        of the integer type used to do the computation,
  222.  
  223.        The visualid member gives the ID number of the visual from
  224.        which the colormap was created.    The killid member gives a
  225.        resource ID that indicates whether the cells held by this
  226.        standard colormap are to be released by freeing the col-
  227.        ormap ID or by calling the _X_K_i_l_l_C_l_i_e_n_t function on the
  228.        indicated resource.  (Note that this method is necessary
  229.        for allocating out of an existing colormap.)
  230.  
  231.        The properties containing the _X_S_t_a_n_d_a_r_d_C_o_l_o_r_m_a_p informa-
  232.        tion have the type RGB_COLOR_MAP.
  233.  
  234. DDIIAAGGNNOOSSTTIICCSS
  235.        _B_a_d_A_l_l_o_c     The server failed to allocate the requested
  236.          resource or server memory.
  237.  
  238.        _B_a_d_A_t_o_m     A value for an Atom argument does not name a
  239.          defined Atom.
  240.  
  241.        _B_a_d_W_i_n_d_o_w A value for a Window argument does not name a
  242.          defined Window.
  243.  
  244. SSEEEE AALLSSOO
  245.        XAllocColor(3X11), XCreateColormap(3X11), XFree(3X11),
  246.        XSetCloseDownMode(3X11)
  247.        _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262. X Version 11           Release 6.1                4
  263.  
  264.  
  265.