1Xbm(3)                User Contributed Perl Documentation               Xbm(3)
2
3
4

NAME

6       Image::Xbm - Load, create, manipulate and save xbm image files.
7

SYNOPSIS

9           use Image::Xbm ;
10
11           my $j = Image::Xbm->new( -file, 'balArrow.xbm' ) ;
12
13           my $i = Image::Xbm->new( -width => 10, -height => 16 ) ;
14
15           my $h = $i->new ; # Copy of $i
16
17           my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
18
19           my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
20
21           my $s = $q->serialse ; # Compresses a little too.
22           my $t = Image::Xbm->new_from_serialsed( $s ) ;
23
24           $i->xybit( 5, 8, 1 ) ;           # Set a bit
25           print '1' if $i->xybit( 9, 3 ) ; # Get a bit
26           print $i->xy( 4, 5 ) ;           # Will print black or white
27
28           $i->vec( 24, 0 ) ;            # Set a bit using a vector offset
29           print '1' if $i->vec( 24 ) ;  # Get a bit using a vector offset
30
31           print $i->get( -width ) ;     # Get and set object and class attributes
32           $i->set( -height, 15 ) ;
33
34           $i->load( 'test.xbm' ) ;
35           $i->save ;
36
37           print "equal\n" if $i->is_equal( $j ) ;
38
39           print $j->as_string ;
40
41           #####-
42           ###---
43           ###---
44           #--#--
45           #---#-
46           -----#
47
48           print $j->as_binstring ;
49
50           1111101110001110001001001000100000010000
51
52       View an xbm file from the command line:
53
54           % perl -MImage::Xbm -e'print Image::Xbm->new(-file,shift)->as_string' file
55
56       Create an xbm file from the command line:
57
58           % perl -MImage::Xbm -e'Image::Xbm->new_from_string("###\n#-#\n-#-")->save("test.xbm")'
59

DESCRIPTION

61       This class module provides basic load, manipulate and save
62       functionality for the xbm file format. It inherits from "Image::Base"
63       which provides additional manipulation functionality, e.g.
64       new_from_image(). See the "Image::Base" pod for information on adding
65       your own functionality to all the "Image::Base" derived classes.
66
67   new()
68           my $i = Image::Xbm->new( -file => 'test.xbm' ) ;
69           my $j = Image::Xbm->new( -width => 12, -height => 18 ) ;
70           my $k = $i->new ;
71
72       We can create a new xbm image by reading in a file, or by creating an
73       image from scratch (all the bits are unset by default), or by copying
74       an image object that we created earlier.
75
76       If we set "-file" then all the other arguments are ignored (since
77       they're taken from the file). If we don't specify a file, "-width" and
78       "-height" are mandatory.
79
80       "-file"
81           The name of the file to read when creating the image. May contain a
82           full path.  This is also the default name used for "load"ing and
83           "save"ing, though it can be overridden when you load or save.
84
85       "-width"
86           The width of the image; taken from the file or set when the object
87           is created; read-only.
88
89       "-height"
90           The height of the image; taken from the file or set when the object
91           is created; read-only.
92
93       "-hotx"
94           The x-coord of the image's hotspot; taken from the file or set when
95           the object is created. Set to -1 if there is no hotspot.
96
97       "-hoty"
98           The y-coord of the image's hotspot; taken from the file or set when
99           the object is created. Set to -1 if there is no hotspot.
100
101       "-bits"
102           The bit vector that stores the image; read-only.
103
104   new_from_string()
105           my $p = Image::Xbm->new_from_string( "###\n#-#\n###" ) ;
106           my $q = $p->new_from_string( "H##", "#-#", "###" ) ;
107           my $r = $p->new_from_string( $p->as_string ) ;
108
109       Create a new bitmap from a string or from an array or list of strings.
110       If you want to use different characters you can:
111
112           Image::Xbm->set( -setch => 'X', -unsetch => ' ' ) ;
113           my $s = $p->new_from_string( "XXX", "X X", "XhX" ) ;
114
115       You can also specify a hotspot by making one of the characters a 'H'
116       (set bit hotspot) or 'h' (unset bit hotspot) -- you can use different
117       characters by setting "-sethotch" and "-unsethotch" respectively.
118
119   new_from_serialised()
120           my $i = Image::Xbm->new_from_serialised( $s ) ;
121
122       Creates an image from a string created with the serialse() method.
123       Since such strings are a little more compressed than xbm files or
124       Image::Xbm objects they might be useful if storing a lot of bitmaps, or
125       for transferring bitmaps over comms links.
126
127   serialise()
128           my $s = $i->serialise ;
129
130       Creates a string version of the image which can be completed recreated
131       using the "new_from_serialised" method.
132
133   get()
134           my $width = $i->get( -width ) ;
135           my( $hotx, $hoty ) = $i->get( -hotx, -hoty ) ;
136
137       Get any of the object's attributes. Multiple attributes may be
138       requested in a single call.
139
140       See "xy" and "vec" to get/set bits of the image itself.
141
142   set()
143           $i->set( -hotx => 120, -hoty => 32 ) ;
144
145       Set any of the object's attributes. Multiple attributes may be set in a
146       single call. Except for "-setch" and "-unsetch" all attributes are
147       object attributes; some attributes are read-only.
148
149       See "xy" and "vec" to get/set bits of the image itself.
150
151   class attributes
152           Image::Xbm->set( -setch => 'X' ) ;
153           $i->set( -setch => '@', -unsetch => '*' ) ;
154
155       "-setch"
156           The character to print set bits as when using "as_string", default
157           is '#'.  This is a class attribute accessible from the class or an
158           object via "get" and "set".
159
160       "-unsetch"
161           The character to print set bits as when using "as_string", default
162           is '-'.  This is a class attribute accessible from the class or an
163           object via "get" and "set".
164
165       "-sethotch"
166           The character to print set bits as when using "as_string", default
167           is 'H'.  This is a class attribute accessible from the class or an
168           object via "get" and "set".
169
170       "-unsethotch"
171           The character to print set bits as when using "as_string", default
172           is 'h'.  This is a class attribute accessible from the class or an
173           object via "get" and "set".
174
175   xybit()
176           $i->xy( 4, 11, 1 ) ;      # Set the bit at point 4,11
177           my $v = $i->xy( 9, 17 ) ; # Get the bit at point 9,17
178
179       Get/set bits using x, y coordinates; coordinates start at 0.
180
181   xy()
182           $i->xy( 4, 11, 'black' ) ;  # Set the bit from a colour at point 4,11
183           my $v = $i->xy( 9, 17 ) ;   # Get the bit as a colour at point 9,17
184
185       Get/set bits using colours using x, y coordinates; coordinates start at
186       0.
187
188       If set with a colour of 'black' or a numeric value > 0 or a string not
189       matching /^#0+$/ then the bit will be set, otherwise it will be
190       cleared.
191
192       If you get a colour you will always get 'black' or 'white'.
193
194   vec()
195           $i->vec( 43, 0 ) ;      # Unset the bit at offset 43
196           my $v = $i->vec( 87 ) ; # Get the bit at offset 87
197
198       Get/set bits using vector offsets; offsets start at 0.
199
200   load()
201           $i->load ;
202           $i->load( 'test.xbm' ) ;
203
204       Load the image whose name is given, or if none is given load the image
205       whose name is in the "-file" attribute.
206
207   save()
208           $i->save ;
209           $i->save( 'test.xbm' ) ;
210
211       Save the image using the name given, or if none is given save the image
212       using the name in the "-file" attribute. The image is saved in xbm
213       format, e.g.
214
215           #define test_width 6
216           #define test_height 6
217           static unsigned char test_bits[] = {
218            0x1f, 0x07, 0x07, 0x09, 0x11, 0x20 } ;
219
220   is_equal()
221           print "equal\n" if $i->is_equal( $j ) ;
222
223       Returns true (1) if the images are equal, false (0) otherwise. Note
224       that hotspots and filenames are ignored, so we compare width, height
225       and the actual bits only.
226
227   as_string()
228           print $i->as_string ;
229
230       Returns the image as a string, e.g.
231
232           #####-
233           ###---
234           ###---
235           #--#--
236           #---#-
237           -----#
238
239       The characters used may be changed by "set"ting the "-setch" and
240       "-unsetch" characters. If you give "as_string" a parameter it will
241       print out the hotspot if present using "-sethotch" or "-unsethotch" as
242       appropriate, e.g.
243
244           print $n->as_string( 1 ) ;
245
246           H##
247           #-#
248           ###
249
250   as_binstring()
251           print $i->as_binstring ;
252
253       Returns the image as a string of 0's and 1's, e.g.
254
255           1111101110001110001001001000100000010000
256

CHANGES

258       2016/02/23 (Slaven Rezic)
259
260       Make sure macro/variable names are always sane.
261
262       More strict parsing of bits.
263
264       2000/11/09
265
266       Added Jerrad Pierce's patch to allow load() to accept filehandles or
267       strings; will document in next release.
268
269       2000/05/05
270
271       Added new_from_serialised() and serialise() methods.
272
273       2000/05/04
274
275       Made xy() compatible with Image::Base, use xybit() for the earlier
276       functionality.
277
278       2000/05/01
279
280       Improved speed of vec(), xy() and as_string().
281
282       Tried use integer to improve speed but according to Benchmark it made
283       the code slower so I dropped it; interestingly perl 5.6.0 was around
284       25% slower than perl 5.004 with and without use integer.
285
286       2000/04/30
287
288       Created.
289

AUTHOR

291       Mark Summerfield. I can be contacted as <summer@perlpress.com> - please
292       include the word 'xbm' in the subject line.
293
295       Copyright (c) Mark Summerfield 2000. All Rights Reserved.
296
297       This module may be used/distributed/modified under the LGPL.
298
299
300
301perl v5.38.0                      2023-07-20                            Xbm(3)
Impressum