home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-bin / x11r6.1 / man / cat3 / xalloccolor.0 < prev    next >
Encoding:
Text File  |  1996-10-17  |  12.6 KB  |  331 lines
  1.  
  2.  
  3.  
  4. XAllocColor(3X11)      XLIB FUNCTIONS    XAllocColor(3X11)
  5.  
  6.  
  7. NNAAMMEE
  8.        XAllocColor, XAllocNamedColor, XAllocColorCells, XAlloc-
  9.        ColorPlanes, XFreeColors - allocate and free colors
  10.  
  11. SSYYNNTTAAXX
  12.        Status XAllocColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _s_c_r_e_e_n___i_n___o_u_t)
  13.          Display *_d_i_s_p_l_a_y;
  14.          Colormap _c_o_l_o_r_m_a_p;
  15.          XColor *_s_c_r_e_e_n___i_n___o_u_t;
  16.  
  17.        Status XAllocNamedColor(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_l_o_r___n_a_m_e,
  18.        _s_c_r_e_e_n___d_e_f___r_e_t_u_r_n, _e_x_a_c_t___d_e_f___r_e_t_u_r_n)
  19.          Display *_d_i_s_p_l_a_y;
  20.          Colormap _c_o_l_o_r_m_a_p;
  21.          char *_c_o_l_o_r___n_a_m_e;
  22.          XColor *_s_c_r_e_e_n___d_e_f___r_e_t_u_r_n, *_e_x_a_c_t___d_e_f___r_e_t_u_r_n;
  23.  
  24.        Status XAllocColorCells(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g,
  25.        _p_l_a_n_e___m_a_s_k_s___r_e_t_u_r_n, _n_p_l_a_n_e_s,
  26.                  _p_i_x_e_l_s___r_e_t_u_r_n, _n_p_i_x_e_l_s)
  27.          Display *_d_i_s_p_l_a_y;
  28.          Colormap _c_o_l_o_r_m_a_p;
  29.          Bool _c_o_n_t_i_g;
  30.          unsigned long _p_l_a_n_e___m_a_s_k_s___r_e_t_u_r_n[];
  31.          unsigned int _n_p_l_a_n_e_s;
  32.          unsigned long _p_i_x_e_l_s___r_e_t_u_r_n[];
  33.          unsigned int _n_p_i_x_e_l_s;
  34.  
  35.        Status XAllocColorPlanes(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _c_o_n_t_i_g,
  36.        _p_i_x_e_l_s___r_e_t_u_r_n, _n_c_o_l_o_r_s, _n_r_e_d_s, _n_g_r_e_e_n_s,
  37.                   _n_b_l_u_e_s, _r_m_a_s_k___r_e_t_u_r_n,
  38.        _g_m_a_s_k___r_e_t_u_r_n, _b_m_a_s_k___r_e_t_u_r_n)
  39.          Display *_d_i_s_p_l_a_y;
  40.          Colormap _c_o_l_o_r_m_a_p;
  41.          Bool _c_o_n_t_i_g;
  42.          unsigned long _p_i_x_e_l_s___r_e_t_u_r_n[];
  43.          int _n_c_o_l_o_r_s;
  44.          int _n_r_e_d_s, _n_g_r_e_e_n_s, _n_b_l_u_e_s;
  45.          unsigned long *_r_m_a_s_k___r_e_t_u_r_n, *_g_m_a_s_k___r_e_t_u_r_n,
  46.        *_b_m_a_s_k___r_e_t_u_r_n;
  47.  
  48.        XFreeColors(_d_i_s_p_l_a_y, _c_o_l_o_r_m_a_p, _p_i_x_e_l_s, _n_p_i_x_e_l_s, _p_l_a_n_e_s)
  49.          Display *_d_i_s_p_l_a_y;
  50.          Colormap _c_o_l_o_r_m_a_p;
  51.          unsigned long _p_i_x_e_l_s[];
  52.          int _n_p_i_x_e_l_s;
  53.          unsigned long _p_l_a_n_e_s;
  54.  
  55. AARRGGUUMMEENNTTSS
  56.        _c_o_l_o_r___n_a_m_e
  57.          Specifies the color name string (for example,
  58.          red) whose color definition structure you want
  59.          returned.
  60.  
  61.  
  62.  
  63.  
  64. X Version 11           Release 6.1                1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. XAllocColor(3X11)      XLIB FUNCTIONS    XAllocColor(3X11)
  71.  
  72.  
  73.        _c_o_l_o_r_m_a_p     Specifies the colormap.
  74.  
  75.        _c_o_n_t_i_g     Specifies a Boolean value that indicates whether
  76.          the planes must be contiguous.
  77.  
  78.        _d_i_s_p_l_a_y     Specifies the connection to the X server.
  79.  
  80.        _e_x_a_c_t___d_e_f___r_e_t_u_r_n
  81.          Returns the exact RGB values.
  82.  
  83.        _n_c_o_l_o_r_s     Specifies the number of pixel values that are to
  84.          be returned in the pixels_return array.
  85.  
  86.        _n_p_i_x_e_l_s     Specifies the number of pixels.
  87.  
  88.        _n_p_l_a_n_e_s     Specifies the number of plane masks that are to
  89.          be returned in the plane masks array.
  90.  
  91.        _n_r_e_d_s
  92.        _n_g_r_e_e_n_s
  93.        _n_b_l_u_e_s
  94.          Specify the number of red, green, and blue
  95.          planes.  The value you pass must be nonnegative.
  96.  
  97.        _p_i_x_e_l_s     Specifies an array of pixel values.
  98.  
  99.        _p_i_x_e_l_s___r_e_t_u_r_n
  100.          Returns an array of pixel values.
  101.  
  102.        _p_l_a_n_e___m_a_s_k___r_e_t_u_r_n
  103.          Returns an array of plane masks.
  104.  
  105.        _p_l_a_n_e_s     Specifies the planes you want to free.
  106.  
  107.        _r_m_a_s_k___r_e_t_u_r_n
  108.        _g_m_a_s_k___r_e_t_u_r_n
  109.        _b_m_a_s_k___r_e_t_u_r_n
  110.          Return bit masks for the red, green, and blue
  111.          planes.
  112.  
  113.        _s_c_r_e_e_n___d_e_f___r_e_t_u_r_n
  114.          Returns the closest RGB values provided by the
  115.          hardware.
  116.  
  117.        _s_c_r_e_e_n___i_n___o_u_t
  118.          Specifies and returns the values actually used
  119.          in the colormap.
  120.  
  121. DDEESSCCRRIIPPTTIIOONN
  122.        The _X_A_l_l_o_c_C_o_l_o_r function allocates a read-only colormap
  123.        entry corresponding to the closest RGB value supported by
  124.        the hardware.  _X_A_l_l_o_c_C_o_l_o_r returns the pixel value of the
  125.        color closest to the specified RGB elements supported by
  126.        the hardware and returns the RGB value actually used.  The
  127.  
  128.  
  129.  
  130. X Version 11           Release 6.1                2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. XAllocColor(3X11)      XLIB FUNCTIONS    XAllocColor(3X11)
  137.  
  138.  
  139.        corresponding colormap cell is read-only.  In addition,
  140.        _X_A_l_l_o_c_C_o_l_o_r returns nonzero if it succeeded or zero if it
  141.        failed.    Multiple clients that request the same effective
  142.        RGB value can be assigned the same read-only entry, thus
  143.        allowing entries to be shared.  When the last client deal-
  144.        locates a shared cell, it is deallocated.  _X_A_l_l_o_c_C_o_l_o_r
  145.        does not use or affect the flags in the _X_C_o_l_o_r structure.
  146.  
  147.        _X_A_l_l_o_c_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.
  148.  
  149.        The _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r function looks up the named color
  150.        with respect to the screen that is associated with the
  151.        specified colormap.  It returns both the exact database
  152.        definition and the closest color supported by the screen.
  153.        The allocated color cell is read-only.  The pixel value is
  154.        returned in screen_def_return.  If the color name is not
  155.        in the Host Portable Character Encoding, the result is
  156.        implementation-dependent.  Use of uppercase or lowercase
  157.        does not matter.     If screen_def_return and
  158.        exact_def_return point to the same structure, the pixel
  159.        field will be set correctly, but the color values are
  160.        undefined.  _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r returns nonzero if a cell is
  161.        allocated; otherwise, it returns zero.
  162.  
  163.        _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r can generate a _B_a_d_C_o_l_o_r error.
  164.  
  165.        The _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s function allocates read/write color
  166.        cells.  The number of colors must be positive and the num-
  167.        ber of planes nonnegative, or a _B_a_d_V_a_l_u_e error results.
  168.        If ncolors and nplanes are requested, then ncolors pixels
  169.        and nplane plane masks are returned.  No mask will have
  170.        any bits set to 1 in common with any other mask or with
  171.        any of the pixels.  By ORing together each pixel with zero
  172.        or more masks, ncolors * 2_n_p_l_a_n_e_s distinct pixels can be
  173.        produced.  All of these are allocated writable by the
  174.        request.     For _G_r_a_y_S_c_a_l_e or _P_s_e_u_d_o_C_o_l_o_r, each mask has
  175.        exactly one bit set to 1.  For _D_i_r_e_c_t_C_o_l_o_r, each has
  176.        exactly three bits set to 1.  If contig is _T_r_u_e and if all
  177.        masks are ORed together, a single contiguous set of bits
  178.        set to 1 will be formed for _G_r_a_y_S_c_a_l_e or _P_s_e_u_d_o_C_o_l_o_r and
  179.        three contiguous sets of bits set to 1 (one within each
  180.        pixel subfield) for _D_i_r_e_c_t_C_o_l_o_r.     The RGB values of the
  181.        allocated entries are undefined.     _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s returns
  182.        nonzero if it succeeded or zero if it failed.
  183.  
  184.        _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e
  185.        errors.
  186.  
  187.        The specified ncolors must be positive; and nreds,
  188.        ngreens, and nblues must be nonnegative, or a _B_a_d_V_a_l_u_e
  189.        error results.  If ncolors colors, nreds reds, ngreens
  190.        greens, and nblues blues are requested, ncolors pixels are
  191.        returned; and the masks have nreds, ngreens, and nblues
  192.        bits set to 1, respectively.  If contig is _T_r_u_e, each mask
  193.  
  194.  
  195.  
  196. X Version 11           Release 6.1                3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. XAllocColor(3X11)      XLIB FUNCTIONS    XAllocColor(3X11)
  203.  
  204.  
  205.        will have a contiguous set of bits set to 1.  No mask will
  206.        have any bits set to 1 in common with any other mask or
  207.        with any of the pixels.    For _D_i_r_e_c_t_C_o_l_o_r, each mask will
  208.        lie within the corresponding pixel subfield.  By ORing
  209.        together subsets of masks with each pixel value, ncolors *
  210.        2(_n_r_e_d_s+_n_g_r_e_e_n_s+_n_b_l_u_e_s) distinct pixel values can be pro-
  211.        duced.  All of these are allocated by the request.  How-
  212.        ever, in the colormap, there are only ncolors * 2_n_r_e_d_s
  213.        independent red entries, ncolors * 2_n_g_r_e_e_n_s independent
  214.        green entries, and ncolors * 2_n_b_l_u_e_s independent blue
  215.        entries.     This is true even for _P_s_e_u_d_o_C_o_l_o_r.  When the
  216.        colormap entry of a pixel value is changed (using
  217.        _X_S_t_o_r_e_C_o_l_o_r_s, _X_S_t_o_r_e_C_o_l_o_r, or _X_S_t_o_r_e_N_a_m_e_d_C_o_l_o_r), the pixel
  218.        is decomposed according to the masks, and the correspond-
  219.        ing independent entries are updated.  _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s
  220.        returns nonzero if it succeeded or zero if it failed.
  221.  
  222.        _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s can generate _B_a_d_C_o_l_o_r and _B_a_d_V_a_l_u_e
  223.        errors.
  224.  
  225.        The _X_F_r_e_e_C_o_l_o_r_s function frees the cells represented by
  226.        pixels whose values are in the pixels array.  The planes
  227.        argument should not have any bits set to 1 in common with
  228.        any of the pixels.  The set of all pixels is produced by
  229.        ORing together subsets of the planes argument with the
  230.        pixels.    The request frees all of these pixels that were
  231.        allocated by the client (using _X_A_l_l_o_c_C_o_l_o_r,
  232.        _X_A_l_l_o_c_N_a_m_e_d_C_o_l_o_r, _X_A_l_l_o_c_C_o_l_o_r_C_e_l_l_s, and
  233.        _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s).  Note that freeing an individual pixel
  234.        obtained from _X_A_l_l_o_c_C_o_l_o_r_P_l_a_n_e_s may not actually allow it
  235.        to be reused until all of its related pixels are also
  236.        freed.  Similarly, a read-only entry is not actually freed
  237.        until it has been freed by all clients, and if a client
  238.        allocates the same read-only entry multiple times, it must
  239.        free the entry that many times before the entry is actu-
  240.        ally freed.
  241.  
  242.        All specified pixels that are allocated by the client in
  243.        the colormap are freed, even if one or more pixels produce
  244.        an error.  If a specified pixel is not a valid index into
  245.        the colormap, a _B_a_d_V_a_l_u_e error results.    If a specified
  246.        pixel is not allocated by the client (that is, is unallo-
  247.        cated or is only allocated by another client) or if the
  248.        colormap was created with all entries writable (by passing
  249.        _A_l_l_o_c_A_l_l to _X_C_r_e_a_t_e_C_o_l_o_r_m_a_p), a _B_a_d_A_c_c_e_s_s error results.
  250.        If more than one pixel is in error, the one that gets
  251.        reported is arbitrary.
  252.  
  253.        _X_F_r_e_e_C_o_l_o_r_s can generate _B_a_d_A_c_c_e_s_s, _B_a_d_C_o_l_o_r, and _B_a_d_V_a_l_u_e
  254.        errors.
  255.  
  256. DDIIAAGGNNOOSSTTIICCSS
  257.        _B_a_d_A_c_c_e_s_s A client attempted to free a color map entry
  258.          that it did not already allocate.
  259.  
  260.  
  261.  
  262. X Version 11           Release 6.1                4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. XAllocColor(3X11)      XLIB FUNCTIONS    XAllocColor(3X11)
  269.  
  270.  
  271.        _B_a_d_A_c_c_e_s_s A client attempted to store into a read-only
  272.          color map entry.
  273.  
  274.        _B_a_d_C_o_l_o_r     A value for a Colormap argument does not name a
  275.          defined Colormap.
  276.  
  277.        _B_a_d_V_a_l_u_e     Some numeric value falls outside the range of
  278.          values accepted by the request.  Unless a spe-
  279.          cific range is specified for an argument, the
  280.          full range defined by the argument's type is
  281.          accepted.  Any argument defined as a set of
  282.          alternatives can generate this error.
  283.  
  284. SSEEEE AALLSSOO
  285.        XCreateColormap(3X11), XQueryColor(3X11), XStoreCol-
  286.        ors(3X11)
  287.        _X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. X Version 11           Release 6.1                5
  329.  
  330.  
  331.