Update upstream source from tag 'upstream/3.026'

Update to upstream version '3.026'
with Debian dir d8536bf85ae20bcf7ac21ae3322a229ea3f49b28

1 files changed, 90 insertions, 18 deletions

diff --git a/lib/PDF/Builder/Resource/XObject/Image.pm b/lib/PDF/Builder/Resource/XObject/Image.pm
index fec9b71..5428f08 100644
--- a/lib/PDF/Builder/Resource/XObject/Image.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.017'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 
@@ -16,12 +16,16 @@ PDF::Builder::Resource::XObject::Image - Base class for external raster image ob
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $image = PDF::Builder::Resource::XObject::Image->new($pdf, $name)
 
-=item $image = PDF::Builder::Resource::XObject::Image->new($pdf, $name)
+=over
 
 Returns an image resource object.
 
+=back
+
 =cut
 
 sub new {
@@ -34,9 +38,22 @@ sub new {
     return $self;
 }
 
-=item $width = $image->width($width)
+=head2 width
+
+    $width = $image->width()
+
+=over
+
+Get the width (in points) of the image object.
+
+B<Note> that this function also has the ability to I<set> the width,
+by giving the new width (in points), but it appears that it never 
+worked correctly. The I<set> capability has been B<deprecated>, and 
+is scheduled to be removed some time after October, 2025. If you are
+using the C<width()> method in some manner to I<set> the image width,
+please let us know, so we can plan to keep it enabled!
 
-Get or set the width value for the image object.
+=back
 
 =cut
 
@@ -47,9 +64,22 @@ sub width {
     return $self->{'Width'}->val();
 }
 
-=item $height = $image->height($height)
+=head2 height
+
+    $height = $image->height()
+
+=over
+
+Get the height (in points) of the image object.
 
-Get or set the height value for the image object.
+B<Note> that this function also has the ability to I<set> the height,
+by giving the new height (in points), but it appears that it never 
+worked correctly. The I<set> capability has been B<deprecated>, and 
+is scheduled to be removed some time after October, 2025. If you are
+using the C<height()> method in some manner to I<set> the image height,
+please let us know, so we can plan to keep it enabled!
+
+=back
 
 =cut
 
@@ -60,10 +90,38 @@ sub height {
     return $self->{'Height'}->val();
 }
 
-=item $image->smask($xobject)
+## probably not useful, so do not add, for now
+#=head2 bbox
+#
+#    ($x1,$x2, $w,$h) = $image->bbox()
+#
+#=over
+#
+#Get the image dimensions similarly to a form's I<bounding box>. 
+#Note that the C<$x1> and C<$x2> values will always be 0.
+#
+#This method is offered as an alternative to the C<width> and C<height> methods.
+#
+#=back
+#
+#=cut
+#
+#sub bbox {
+#    my $self = shift();
+#    my @bb = (0,0, $self->width(),$self->height());
+#    return @bb;
+#}
+
+=head2 smask
+
+    $image->smask($xobject)
+
+=over
 
 Set the soft-mask image object.
 
+=back
+
 =cut
 
 sub smask {
@@ -73,13 +131,19 @@ sub smask {
     return $self;
 }
 
-=item $image->mask(@color_range)
+=head2 mask
+
+    $image->mask(@color_range)
 
-=item $image->mask($xobject)
+    $image->mask($xobject)
+
+=over
 
 Set the mask to an image mask XObject or an array containing a range
 of colors to be applied as a color key mask.
 
+=back
+
 =cut
 
 sub mask {
@@ -96,9 +160,13 @@ sub mask {
 
 # imask() functionality rolled into mask()
 
-=item $image->colorspace($name)
+=head2 colorspace
+
+    $image->colorspace($name)
 
-=item $image->colorspace($array)
+    $image->colorspace($array)
+
+=over
 
 Set the color space used by the image. Depending on the color space,
 this will either be just the name of the color space, or it will be an
@@ -108,6 +176,8 @@ If passing an array, parameters must already be encoded as PDF
 objects. The array itself may also be a PDF object. If not, one will
 be created.
 
+=back
+
 =cut
 
 sub colorspace {
@@ -124,10 +194,16 @@ sub colorspace {
     return $self;
 }
 
-=item $image->bits_per_component($integer)
+=head2 bits_per_component
+
+    $image->bits_per_component($integer)
+
+=over
 
 Set the number of bits used to represent each color component.
 
+=back
+
 =cut
 
 sub bits_per_component {
@@ -140,8 +216,4 @@ sub bits_per_component {
 
 # bpc() renamed to bits_per_component()
 
-=back
-
-=cut
-
 1;