NAME

       Text::Layout::PDFAPI2::ImageElement - <img> element for PDF images

DESCRIPTION

       This class implements support for an "<img>" element. It can be used to include inline images in marked-
       up texts.

       The class provides the three mandatory methods according to the requirements of
       Text::Layout::ElementRole.

       parse
           To parse the "<img>" tag in marked-up text.

       bbox
           To provide the augmented bounding box for the image.

       render
           To render the image using one of the PDF::API2 compatible libraries.

       An  additional,  overridable  method getimage() is provided to actually produce the desired image object.
       See "IMAGE PRODUCER"

THE "<img>" ELEMENT

           <img attributes />

       Note that the "<img>" element must be self-closed, i.e., end with "/>".

       The image is placed at the current location in the text and aligned on the  baseline  of  the  text.  The
       image dimensions contribute to the resultant bounding box of the formatted text. See "dx" and "dy" below.

       All attributes are key=value pairs. The value should (but need not) be enclosed in quotes.

       Dimensional values may be a (fractional) number optionally postfixed by "em" or "ex", or a percentage.  A
       number  indicates  points.   "em"  values  are  multiplied  by  the current font size and "ex" values are
       multiplied by half the font size.

       "src="IMAGE
           Provides the source of the image. This can be the filename of a jpg, png or gif image.

       "width="NNN
           The desired width for the image.  Dimensional.  The image is scaled if necessary.

       "height="NNN
           The desired height for the image.  Dimensional.  The image is scaled if necessary.

       "dx="NNN
           A horizontal offset for the image, wrt. the current location in the text.  Dimensional.

       "dy="NNN
           Same, but vertical. Positive amounts move up.

           Note the direction is opposite to the Pango "rise".

       "scale="NNN
           A scaling factor, to be applied after  width/height  scaling.   The  value  may  be  expressed  as  a
           percentage.

           Independent horizontal and vertical scaling can be specified as two comma-separated scale values.

       "align="XXX
           Align the image in the width given by "w="NNN.

           Possible alignments are "left", "center", and "right".

       "bbox="N
           If true, the actual bounding box of an object is used for placement.

           By default the bounding box is only used to obtain the width and height.

           This attribute has no effect on image objects.

       "w="NNN
           The  advance  width  of  the image.  Dimensional.  Default advance is the image width plus horizontal
           offset.  This overrides the advance and may be zero.

       "h="NNN
           The advance height of the image.  Dimensional.  Default advance is the  image  height  plus  vertical
           offset.  This overrides the advance and may be zero.

CONSTRUCTOR

       This class is usually instantiated in a Text::Layout register_element call:

           $layout->register_element
             ( Text::Layout::PDFAPI2::ImageElement->new( pdf => $pdf ) );

IMAGE PRODUCER

       The image object is produced with a call to method getimage(), that can be overridden in a subclass.  The
       method  gets  a hash ref as argument.  This hash contains all the attributes and may be used for cacheing
       purposes.

       For example,

           method getimage ($fragment) {
               $fragment->{_img} //= $self->pdf->image($fragment->{src});
           }

       An overridden getimage() may produce a PDF XObject instead of an image  object.  An  XObject  is  treated
       similar  to an image object, but is aligned according to its bounding box if attribute "bbox" is set to a
       true value, i.e., not zero.

SEE ALSO

       Text::Layout, PDF::API2, PDF::Builder.

AUTHOR

       Johan Vromans, "<JV at CPAN dot org>"

SUPPORT

       This class is part of <Text::Layout>.

       Development takes place on GitHub: <https://github.com/sciurius/perl-Text-Layout>.

       Please report any bugs or feature requests using the issue tracker for Text::Layout on GitHub.

LICENSE

       See Text::Layout.

perl v5.40.1                                       2025-08-15              Text::Layout::...2::ImageElement(3pm)