/ 
Image-Base-X11-Protocol-2
River stage zero No dependents
/ Image::Base::X11::Protocol::Drawable

NAME

Image::Base::X11::Protocol::Drawable -- draw into an X11::Protocol window or pixmap

SYNOPSIS

use Image::Base::X11::Protocol::Drawable;
my $X = X11::Protocol->new;

my $image = Image::Base::X11::Protocol::Drawable->new
              (-X        => $X,
               -drawable => $xid,
               -colormap => $colormap);
$image->line (0,0, 99,99, '#FF00FF');
$image->rectangle (10,10, 20,15, 'white');

CLASS HIERARCHY

Image::Base::X11::Protocol::Drawable is a subclass of Image::Base,

Image::Base
  Image::Base::X11::Protocol::Drawable

DESCRIPTION

Image::Base::X11::Protocol::Drawable extends Image::Base to draw into X windows or pixmaps by sending drawing requests to an X server with X11::Protocol. There's no file load or save, just drawing operations.

The subclasses Image::Base::X11::Protocol::Pixmap and Image::Base::X11::Protocol::Window have things specific to a pixmap or window respectively. Drawable is the common parts.

Colour names are anything known to the X server (usually in the file /etc/X11/rgb.txt), or 2-digit or 4-digit hex #RRGGBB and #RRRRGGGGBBBB. Colours used are allocated in a specified -colormap. For bitmaps pixel values 1 and 0 can be used directly, plus special names "set" and "clear".

Native X drawing does much more than Image::Base but if you have some generic pixel twiddling code for Image::Base then this Drawable class lets you point it at an X window etc. Drawing into a window is a good way to show slow drawing progressively, rather than drawing into a pixmap or image file and only displaying when complete. See Image::Base::Multiplex for a way to do both simultaneously.

FUNCTIONS

$image = Image::Base::X11::Protocol::Drawable->new (key=>value,...)

Create and return a new image object. This requires an X11::Protocol connection object and a drawable XID (an integer).

my $image = Image::Base::X11::Protocol::Drawable->new
              (-X        => $x11_protocol_obj,
               -drawable => $drawable_xid,
               -colormap => $X->{'default_colormap'});

A colormap should be given if allocating colours (anything except a bitmap normally).

$colour = $image->xy ($x, $y)
$image->xy ($x, $y, $colour)

Get or set the pixel at $x,$y.

Fetching a pixel is an X server round-trip so reading a big region will be slow. The protocol allows a big region or an entire drawable to be read in one go, so some function for that could be made if needed.

In the current code the colour returned is either the name used to draw it, or looked up in the -colormap to give 4-digit hex #RRRRGGGGBBBB, or otherwise a raw pixel value. If two colour names became the same pixel value because that was as close as could be represented then fetching might give either name. The hex return is 4 digits because that's the range in the X protocol.

If the drawable is a window then parts overlapped by another window (including a sub-window) generally read back as an unspecified value. Parts of a window which are off-screen have no data at all and the return is currently an empty string "". (Would undef or the window background pixel be better?)

$image->add_colours ($name, $name, ...)

Allocate colours in the -colormap. Colour names are the same as for the drawing functions. For example,

$image->add_colours ('red', 'green', '#FF00FF');

The drawing functions automatically add a colour if it doesn't already exist but using add_colours can do a set of pixel lookups in a single server round-trip instead of separate individual ones.

If using the default colormap of the screen then names "black" and "white" are taken from the screen info and don't query the server (neither in the drawing operations nor add_colours).

All colours, both named and hex, are sent to the server for interpretation. On a static visual like TrueColor a hex RGB could in principle be turned into a pixel just on the client side, but the X specs allow non-linear weirdness in how pixel values ramp to RGB component levels, so only the server can do it properly.

ATTRIBUTES

-drawable (integer XID)

The target drawable.

-colormap (integer XID)

The colormap in which to allocate colours when drawing.

Setting -colormap only affects where colours are allocated. If the drawable is a window then the colormap is not set into the window's attributes.

-width (integer, read-only)
-height (integer, read-only)

Width and height are read-only. get queries the server with GetGeometry when required and then caches. If you already know the size then including values in the new will record them ready for later get. The plain drawing operations don't need the size though.

$image = Image::Base::X11::Protocol::Drawable->new
             (-X        => $x11_protocol_obj,
              -drawable => $id,
              -width    => 200,      # known values to
              -height   => 100,      # avoid server query
              -colormap => $colormap);
-depth (integer, read-only)

The depth of the drawable, meaning how many bits per pixel.

-screen (integer, read-only)

The screen number of the -drawable, for example 0 for the first screen.

The depth and screen of a drawable cannot be changed, and for the purposes of this interface the width and height are regarded as fixed too. If you get the -width, -height, -depth or -screen then for a root window the values are obtained from the X11::Protocol object data, or for other drawables by a GetGeometry to the server. If you already know the values of some of these attributes then you can include them in the new to record them ready for later get and avoid that GetGeometry query. Of course if nothing ever does such a get then there's no need.

BUGS

The pixel values for each colour used in drawing are cached for later re-use. This is important to avoid a server round-trip on every drawing operation, but if you use a lot of different shades then the cache may become big. Perhaps some sort of least recently used discard could keep a lid on it. The intention is probably to have a colour-to-pixel or some such property which could be both initialized or manipulated as required.

SEE ALSO

Image::Base, Image::Base::X11::Protocol::Pixmap, Image::Base::X11::Protocol::Window, X11::Protocol, Image::Base::Multiplex

HOME PAGE

http://user42.tuxfamily.org/image-base-x11-protocol/index.html

LICENSE

Image-Base-X11-Protocol is Copyright 2010 Kevin Ryde

Image-Base-X11-Protocol is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Image-Base-X11-Protocol is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Image-Base-X11-Protocol. If not, see <http://www.gnu.org/licenses/>.