summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/graphicxsp/grxsp_man.tex
blob: 9d24d8615fabd1499afaed66a9a9afd94446d898 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
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
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,linktoattachments,aebxmp
]{aeb_pro}
\usepackage{aeb_mlink}
\usepackage[dvipsone,showembeds]{graphicxsp}\previewOff
\usepackage{array,fancyvrb}

%\usepackage[LY1]{fontenc}
%\usepackage[scaled=0.93]{helvet}
%\usepackage{mtpro}

%\usepackage{myriadpro}

%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}


%\usepackage{makeidx}\makeindex

\usepackage{acroman}
\usepackage[active]{srcltx}

\urlstyle{tt}

\def\tutpath{doc/tutorial}
\def\tutpathi{tutorial}
\def\expath{../examples}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={ \texorpdfstring{\pkg{GraphicxSP}\\[1em]}
        {GraphicxSP: }Using and re-using Embedded Graphics},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for AeB Pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.0.2, 2018/11/20},
    Keywords={XMP, E4X, Adobe Acrobat, JavaScript},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$}
\def\meta#1{\textit{\texttt{#1}}}
\let\meta\anglemeta
\def\darg#1{\texttt{\{#1\}}}
\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei}
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
\let\pkg\textsf
\let\env\texttt
\let\opt\texttt
\let\app\textsf

\let\amtIndent\leftmargini
\def\SUB#1{${}_{\text{#1}}$}

\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep
\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}%
\def\eVerb{\vskip\aebdimen\endgroup\noindent}

\def\setDisplayNumber#1#2{\kern0pt
    \setlength\abovedisplayshortskip{0pt}%
    \setlength\belowdisplayshortskip{0pt}%
    \setlength\abovedisplayskip{0pt}%
    \setlength\belowdisplayskip{0pt}%
    \begin{equation}\label{#2}\end{equation}\kern0pt
}


\makeatletter
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.5em}}
\renewcommand*\descriptionlabel[1]{\hspace\labelsep
    \normalfont #1}
\newcommand{\aebDescriptionlabel}[1]{%
    \setlength\dimen@{\amtIndent+\labelsep}%
    {\hspace*{\dimen@}#1}}
\makeatother
\newenvironment{aebDescript}
    {\begin{list}{}{\setlength{\labelwidth}{0pt}%
        \setlength{\leftmargin}{\leftmargin}%
        \setlength{\leftmargin}{\leftmargin+\amtIndent}%
        \setlength\itemindent{-\leftmargin}%
        \let\makelabel\aebDescriptionlabel
    }}{\end{list}}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

%\pagestyle{empty}
%\parindent0pt\parskip\medskipamount

\special{!userdict begin
    /Draw_Ellipse {
        /m matrix currentmatrix def
        4 2 roll translate scale
        0 0 1 0 360 arc
        closepath
        m setmatrix
    } def end
}
\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon}
\embedEPS[hiresbb,transparencyGroup]{myBG}{graphics/border1}

\begin{createImage}{\bboxOf{myBestPic}}{upsideDownAD}
     0 \heightOf{myBestPic} rmoveto
     currentpoint translate
     1 -1 scale [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{\bboxOf{myBestPic}}{transparentAD}
    [ /ca .3 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{\bboxOf{myBestPic}}{nAdobeDon}
    [ {myBestPic} /SP pdfmark
\end{createImage}
\begin{createImage}{\bboxOf{myBestPic}}{dAdobeDon}
    [ /ca .3 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{\bboxOf{myBestPic}}{rAdobeDon}
    [ /ca .5 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{0 0 100 100}{xO}
.7529 setgray 0 0 100 100 rectfill 1 setgray 2 2 moveto 2 98 lineto
98 98 lineto 96 96 lineto 4 96 lineto 4 4 lineto fill 0.34 setgray
98 98 moveto 98 2 lineto 2 2 lineto 4 4 lineto 96 4 lineto
96 96 lineto fill 0 setgray 22.5 22.5 moveto 1 0 0 setrgbcolor
/Helvetica 72 selectfont (O) show
\end{createImage}


\definePath\bgPath{"C:/Users/Public/Documents/%
    ManualBGs/Manual_BG_Print_AeB.pdf"}
\begin{docassembly}
\addWatermarkFromFile({%
    bOnTop: false,
    cDIPath: \bgPath
})
\executeSave()
\end{docassembly}

\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}

Beginning with Version 5.0, ``Acrobat Distiller allows a Postscript
language program to specify that a given set of graphical operations
should be encapsulated and treated as a single object. The pdfmarks
\textbf{BP} (Begin Picture) and \textbf{EP} (End Picture) enclose a
set of graphic operations. The \textbf{SP} (Show Picture) pdfmark
indicates where to insert an object (which may be inserted in more
than one place).''\,\footnote{Section 4.6.1 of the \textit{pdfmark
Reference Manual}, Technical Note \#5150, Version 5.0} This is the
approach taken by this package.

\pkg{GraphicxSP} includes commands for embedding an EPS graphic (using the
\textbf{BP} and \textbf{EP} pdfmark operators) in a PDF derived from
a {\LaTeX} source and for displaying the graphic, possibly multiple
times. For documents that use the same graphic multiple times (for
backgrounds, watermarks, company logos, appearances for form fields,
etc.) using \pkg{GraphicxSP} will (greatly) reduce the size of the
PDF.\footnote{The amount of reduction in file size depends on how
many times a particular graphic is repeatedly used.}

The PDF 1.4 (Acrobat version 5.0) introduces the notion of
transparency into the Adobe imaging model. Support for transparency
through the pdfmark paradigm does not appear until Version
6.0.\,\footnote{Section 4.6.1 of the \textit{pdfmark Reference
Manual}, Technical Note \#5150, Version 6.0, page~33.} This package
also supports transparency feature through the
\textbf{SetTransparency} pdfmark.

\pkg{GraphicxSP}, as the name might suggest, is an extension of the
graphicx package. Functionality for \pkg{GraphicxSP} is accessed through
the \cs{includegrapics} command. Additional key-values for the
\cs{includegrapics} command are defined that support the use
\pkg{GraphicxSP}.

\section{Requirements}

{\LaTeX}, PDF, and transparency requirements are discussed in this section.

\subsection{{\LaTeX} package requirements}

This package requires the \pkg{graphicx} package (by D. P. Carlisle and S. P. Q.
Rahtz), the \pkg{eso-pic} package (by Rolf Niepraschk) and the \pkg{everyshi}
package (by Martin Schr\"oder). \pkg{GraphicxSP} redefines a few commands of the
first two packages: the \pkg{graphics}/\pkg{graphicx} package commands \cs{Gin@setfile}
and \cs{Gin@getbase} are redefined, as is the \pkg{eso-pic} command \cs{@ShipoutPicture}.

\pkg{AeB} (Acro\negthinspace\TeX{} eDucation Bundle) is not a required
package, but to successfully compile the example
\texttt{grxsp\_forms\_aeb.tex}, you need the latest \pkg{AeB} as some
modification to the eforms package were made. See
\mlurl{http://www.math.uakron.edu/~dpstory/graphicxsp.html} for the latest
version.

\subsection{PDF creator requirements}

The big restriction on this package is the requirement to use
\textbf{Acrobat Distiller} (version 5.0, or version 6.0 for transparency).
The package was developed using Acrobat Distiller 8.1. The package supports the
creation of Postscript using \app{dvips} and \app{dvipsone}.

Though distiller is required, there is no reason why, however, this
package can't be modified to work for any PDF creator that supports
the pdfmark; in particular, I invite anyone to extend this package
to \app{GhostScript}.

\subsection{Transparency requirements}

To get the transparency effect, \app{Acrobat Distiller} version 6.0 or
later is required. The default setting of the distiller does not
support the \textbf{SetTransparency} pdfmark; it is necessary to
edit the \texttt{.joboptions} file.

\newtopic\noindent
The procedure for editing \texttt{.joboptions} to support transparency is as follows:
\begin{enumerate}
    \item Start Acrobat Distiller

    \item From the Default Settings list, select the setting you want to
        edit, usually, this will be the \texttt{Standard} job options.
    \item Select \textsf{Settings\;>\;Edit\;Adobe\;PDF\;Settings\;(Ctrl+E)}
        from the distiller menu.
    \item Click the \texttt{SaveAs} button at the bottom of the
        \texttt{Adobe PDF Settings} dialog box. Save your
        \texttt{.jobsettings} file under a new name, say
        \texttt{Standard\_transparency} and make a note of where the
        distiller saves this file.
    \item With your favorite text editor, navigate to the folder where you
        saved your new \texttt{.joboptions} file, and open it in your
        editor.
    \item Look for the line \texttt{/AllowTransparency false}, change
        \texttt{false} to \texttt{true} so that it now reads
        \texttt{/AllowTransparency true}. Save the changes and close the
        file.
    \item Use this \texttt{.joboptions} file,
        \texttt{Standard\_transparency} for example, whenever you distill
        with transparency pdfmarks.  If your {\LaTeX} file uses
        transparency, and you are using a \texttt{.joboptions} file with
        \texttt{/AllowTransparency false}, distillation will fail and the
        distiller log should say
\begin{Verbatim}[fontsize=\small]
%%[Error: The Postscript contains Transparency pdfmark, job aborted.]%%
%%[ /AllowTransparency is false in job option settings.]%%
%%[ Error: undefined; OffendingCommand: pdfmark;
    ErrorInfo: Transparency Group ]%%
\end{Verbatim}
This suggests that you should use your \texttt{.joboptions} file that supports transparency!

\end{enumerate}

\section{Options of this package}

Currently, there is a minimal of package options

\begin{itemize}
\item \texttt{dvips}: Use this option if you are a user of most any other
    {\TeX} systems available to the community.
\item \texttt{dvipsone}: Use this option if you are a user of the Y{\small\&}\!Y
    {\TeX} system to create your Postscript file.
\item \texttt{preview}: The dvi previewers are designed to show a preview
    of the graphic, these previewers know nothing about the \textbf{SP}
    pdfmark (Show Picture). If you use the \texttt{preview} option, a
    \cs{fbox} is placed around all graphics inserted by the
    \pkg{GraphicxSP} package. This option sets a boolean switch,
    \cs{ifpreview} to true. You are free to locally set this switch to get
    the \cs{fbox} to appear, use include \cs{previewtrue} in your document,
    or, to turn the preview off again, type \cs{previewfalse}.
\item \texttt{showembeds}: As just mentioned, dvi previewers are
    designed to preview graphics; consequently, the graphic files
    embedded by \pkg{GraphicxSP}, will have a preview as well. The
    embedding command \cs{embedEPS} is required to appear only in
    the preamble, so the preview for this embedded graphics always
    appears on the first page. \pkg{GraphicxSP} covers these embedded
    files using a white \texttt{colorbox}; content and other
    graphics are placed on top of the white \texttt{colorbox}. Using
    the \texttt{showembeds} will cause this white color box not to
    be created, hence, you can see the dvi preview of the embedded
    graphics, stacked one on top of the other.
\item \texttt{draft}: Similar to the option of the same name in the
    graphicx package. Instead of displaying an image, a rectangular
    box is displayed with the name of the graphic in its interior.
\item \texttt{shownonames}: If this option is chosen along with
    the \texttt{draft} option, the name of the graphic is not displayed.
\end{itemize}

\section{The \texorpdfstring{\protect\pkg{GraphicxSP}}{GraphicxSP} commands}

In this section we present the new commands defined in the \pkg{GraphicxSP} package.

\subsection{Embedding commands}

Before we can show a graphic, we first must embed it using the
\cs{embedEPS} command.
\bVerb\takeMeasure{\string\embedEPS[\meta{key-values}]\darg{\meta{name}}\darg{\meta{path}}}
\begin{dCmd}[commandchars=!()]{\bxSize}
\embedEPS[!meta(key-values)]{!meta(name)}{!meta(path)}
\end{dCmd}
\endgroup
\CmdLoc This command is restricted to the preamble.

\PD The parameters are as follows:
\begin{enumerate}
\item The first optional parameter takes key-value pairs:
\begin{itemize}
    \item \texttt{hiresbb}: This is a key from the graphicx package.
        When this key is present, graphicx will look for the high
        resolution bounding box; otherwise, is looks for the
        bounding box.
    \item \texttt{transparencyGroup}: Use this key if the embedded
        graphic is to be used with transparency. The key is normally
        used by itself, but it can be given values, a good old-fashion
        reading of Chapter 7 on Transparency in the PDF Reference, sixth
        edition, version 1.7, is necessary.
\end{itemize}
\item The second parameter \meta{name} is the symbolic name for
the graphic. This symbolic name must be unique to the document (or
distiller will crash); \pkg{GraphicxSP} will stop compilation if two
embedded EPS files are given the same name.
\item The third parameter is the path to the graphic, an EPS
graphic. The graphic can be in the current folder, or on the
graphics search path. The same rules hold here as in the graphicx
package.
\end{enumerate}
For example,
\bVerb\takeMeasure{\string\embedEPS[hiresbb,transparencyGroup]\darg{myBestPic}\darg{graphics/AdobeDon}}
\begin{dCmd*}[commandchars=!()]{\bxSize}
\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon}
\end{dCmd*}
\eVerb
When a file is embedded, certain parameters are saved and are
available for use by the document author. Each of the commands below
take the symbolic name, \meta{name} of the graphic as their only
argument.
\begin{itemize}
\item \cs{bboxOf\darg{\meta{name}}}: The dimensions of the bounding box,
    \texttt{llx} \texttt{lly} \texttt{urx} \texttt{ury}, of the graphic
    with symbolic name \meta{name}. The individual values of this bounding box
    can be accessed by the next four commands.

\item \cs{llxOf\darg{\meta{name}}}: The lower left x-coordinate of the
    (high res) bounding box as read by graphicx.

\item \cs{llyOf\darg{\meta{name}}}: The lower left y-coordinate of the
    (high res) bounding box as read by graphicx.

\item \cs{urxOf\darg{\meta{name}}}: The upper left x-coordinate of the
    (high res) bounding box as read by graphicx.

\item \cs{uryOf\darg{\meta{name}}}: The upper left y-coordinate of the
    (high res) bounding box as read by graphicx.

\item \cs{heightOf\darg{\meta{name}}}: The height of the graphic, based on
    the bounding box information, \cs{uryOf\darg{\meta{name}}} -
    \cs{llyOf\darg{\meta{name}}}.

\item \cs{widthOf\darg{\meta{name}}}: The width of the graphic, based on
    the bounding box information, \cs{urxOf\darg{\meta{name}}} -
    \cs{llxOf\darg{\meta{name}}}.
\end{itemize}
Each expands to a number representing Adobe points. To convert these
numbers for use by {\TeX} just add the suffix \texttt{bp}, e.g., in
{\TeX} space, the height of the graphic is \cs{heightOf\darg{\meta{name}}bp}.

These commands are useful when creating variations on an
\cs{embedEPS} graphic using the \texttt{createImage} environment
defined below, or for creating form fields with an \cs{embedEPS}
graphic as an appearance.

The \cs{embedEPS} command is designed for graphics that are in an exterior
EPS file. You can also define a graphic, or image, using raw
Postscript using the \Indextt{createImage} environment.

%\bVerb\takeMeasure{\string\begin\darg{createImage}[\meta{key-values}]\darg{\meta{bbox}}\darg{\meta{name}}}
%\begin{dCmd}[commandchars=!()]{\bxSize}
%\begin{createImage}[!meta(key-values)]{!meta(bbox)}{!meta(name)}
%    !meta(postscript code)
%\end{createImage}
%\end{dCmd}
%\eVerb


\bVerb\takeMeasure{\string\begin\darg{createImage}[\meta{key-values}]\darg{\meta{bbox}}\darg{\meta{name}}}
\begin{minipage}[c]{\linewidth}
\begin{minipage}[c]{\bxSize}
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{createImage}[!meta(key-values)]{!meta(bbox)}{!meta(name)}
    !meta(postscript code)
\end{createImage}
\end{dCmd}
\end{minipage}\hfill
\begin{minipage}[c]{\linewidth-(\bxSize)}
\setDisplayNumber\label{createImg}
\end{minipage}
\end{minipage}\medskip
\eVerb The \env{createImage} environment defines a command \cs{\meta{name}} that expands to
\meta{name}. If \cs{\meta{name}} is already defined, a message appears in the log to that effect.
Normally \meta{name} consists of non-active characters; however, if other characters are used,
the command \cs{csOf\darg{\meta{name}}} can be used. The \cs{\meta{name}} command was created to support
the \pkg{icon-appr} package.

\PD The parameters are as follows:
\begin{enumerate}
\item The first optional parameter takes key-value pairs:
\begin{itemize}
    \item \texttt{transparencyGroup}: Use this key if the embedded
        graphic is to be use with transparency. The key is normally
        used by itself, but it can be given values, a good
        old-fashion reading of Chapter 7 on Transparency in the PDF
        Reference, sixth edition, version 1.7, is necessary.
\end{itemize}
\item The second parameter, \meta{bbox}, is the bounding box of the
image being created.
\item The third parameter \meta{name} is the symbolic name for
the graphic. This symbolic name must be unique to the document (or
distiller will crash); \pkg{GraphicxSP} will stop compilation if two
embedded EPS files are given the same name.
\end{enumerate}
The following image appears in one of the demo files of this package, and is code
written many years ago for a tic-tac-toe game in PDF.
\begin{Verbatim}
\begin{createImage}{0 0 100 100}{xO}
.7529 setgray 0 0 100 100 rectfill 1 setgray 2 2 moveto 2 98 lineto
98 98 lineto 96 96 lineto 4 96 lineto 4 4 lineto fill 0.34 setgray
98 98 moveto 98 2 lineto 2 2 lineto 4 4 lineto 96 4 lineto
96 96 lineto fill 0 setgray 22.5 22.5 moveto 1 0 0 setrgbcolor
/Helvetica 72 selectfont (O) show
\end{createImage}
\end{Verbatim}

\begin{Verbatim}
\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon}
\end{Verbatim}
we can then manipulate this image a little
\begin{Verbatim}
\begin{createImage}{\bboxOf{myBestPic}}{upsideDownAD}
     0 \heightOf{myBestPic} rmoveto
     currentpoint translate
     1 -1 scale [ {myBestPic} /SP pdfmark
\end{createImage}
\end{Verbatim}
Notice that we reposition the graphic to fit inside the bounding box.

I don't mean to get ahead of myself, but you can introduce transparency as well.

\begin{Verbatim}
\begin{createImage}{\bbox{myBestPic}}{transparentAD}
    [ /ca .3 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}
\end{Verbatim}
All these examples will appear again below when \cs{includegraphics} and \cs{insertEPS}
are discussed.

\newtopic\noindent
The commands \cs{llxOf}, \cs{llyOf}, \cs{urxOf}, \cs{uryOf}, \cs{bboxOf},
\cs{heightOf} and \cs{widthOf} are also defined for images created by the
\texttt{createImage} environment.


\subsection{Inserting graphics commands}

Once we have embedded our graphics using \cs{embedEPS} or create a
new image or modified an old image using the \texttt{createImage}
environment, we can display them to our heart's content. There are two
commands for displaying a embedded graphic, \cs{includegraphics} and
\cs{insertEPS}.

\bVerb\takeMeasure{\string\includegraphics[name=\meta{name},\meta{key-values}]\darg{\meta{path}}}
\begin{dCmd}[commandchars=!()]{\bxSize}
\includegraphics[name=!meta(name),!meta(key-values)]{!meta(path)}
\insertEPS[!meta(key-values)]{!meta(name)}
\end{dCmd}
\endgroup

\PD The \meta{name} key is required in the \cs{includegraphics}
command, the value is the symbolic \meta{name} of the graphic to
be used. When the name key is used, the \meta{path} parameter is not
used in \pkg{GraphicxSP} and can actually be empty; if the name key is not
specified, then \cs{includegraphics} behaves just like it always
does, includes the file in the document and displays it. Because
\meta{path} is not used with SP graphics, \pkg{GraphicxSP} offers
\cs{insertEPS} as an alternative; here the \meta{name} is given as the
second argument. The \meta{key-values} are described next.

\KVP Both commands take all the key-values of the \cs{includegraphics} command, plus
a few more:
\begin{enumerate}
    \item \texttt{name=\meta{name}}: The symbolic name (\meta{name}) for
        the graphic, it is required with the \cs{includegraphics} command,
        and is ignored in the \cs{insertEPS} command. In the later command,
        \meta{name} is entered as the second argument.

    \item \texttt{transparency=\meta{key-values}}: Here you can enter
    various key-value pairs for setting transparency. These
    keys-values are listed in the pdfmark Reference in the section
    on the SetTransparency pdfmark. Of the ones listed, I've only explored
    \textbf{BM}, \textbf{ca} and \textbf{CA}. The following come from the pdfmark Reference on these three:
    \begin{itemize}
        \item \textbf{CA}: Current stroking alpha constant,
        specifying the constant shape or constant opacity value to
        be used for stroking operations. Default is 1.0.
        \item \textbf{ca}: Same as CA, but for nonstroking operation. Default is 1.0.
        \item \textbf{BM}: Current blend mode. Default is Normal.
            Other blend modes are Normal, Multiply, Screen,
            Darken, Lighten, ColorDodge, ColorBurn, HardLight,
            SoftLight, Difference, Exclusion. See the PDF
            Reference for a description of these.

    \end{itemize}
    The most useful of these is \textbf{ca}, and it is illustrated
    in the demo files and well as here.

    \item[] \textbf{Example:} \verb!transparency={/ca .3 /BM/Normal}!

    \item \texttt{presp=\meta{postscript}}: This allows you to insert
        Postscript commands just before \textbf{SP} pdfmark.
    \item \texttt{postsp=\meta{postscript}}: This allows you to insert
        Postscript commands just after \textbf{SP} pdfmark.
\end{enumerate}
The latter two key-values can be used to create special effects, as illustrated below.

\subsection{Examples}

%\previewtrue

\begin{center}
\includegraphics[name=myBestPic,width=1in]{}\\
\small\verb!\includegraphics[name=myBestPic,width=1in]{}!
\end{center}

Below is the image created not from a EPS file, but from Postscript language code.

\begin{center}
\includegraphics[name=xO,width=1in]{}\\
\small\verb!\includegraphics[name=x0,width=1in]{}!
\end{center}

The \meta{path} argument can remain empty as it is not used when the name key is
present. Now, we'll switch over to the shorter \cs{embedEPS} command.

Here is the image created earlier using the \texttt{createImage} environment. The same effect
can be done with \cs{scalebox}.

\begin{center}
\insertEPS[width=1in]{upsideDownAD}\\
\verb!\insertEPS[width=1in]{upsideDownAD}!
\end{center}

Below is the transparent image created using the \texttt{createImage} environment. The same effect
can be done by setting the \texttt{transparency} key set to \verb!{/ca .3}!. The background is white
and it is this white background you see showing through the image.

\begin{center}
\insertEPS[width=1in]{transparentAD}\\
\verb!\insertEPS[width=1in]{transparentAD}!
\end{center}



Next, we set the \texttt{transparency} key to an opacity value ranging from 70\% on the left (\texttt{/ca .7})
to 30\% on the right (\texttt{/ca .3}), and place a colorful background under the
image so you can see the transparency of the image.

\begin{center}\previewfalse
\insertEPS[width=\linewidth,height=80pt]{myBG} %transparency={/ca .3 /BM/Normal},
\smash{\raisebox{15pt}{\makebox[\linewidth][c]{%
\insertEPS[width=1in,transparency={/ca .7}]{myBestPic}\hfill
\insertEPS[width=1in,transparency={/ca .6}]{myBestPic}\hfill
\insertEPS[width=1in,transparency={/ca .5}]{myBestPic}\hfill
\insertEPS[width=1in,transparency={/ca .4}]{myBestPic}\hfill
\insertEPS[width=1in,transparency={/ca .3}]{myBestPic}}}}
\small\verb!transparency={/ca .7}...transparency={/ca .3}!
\end{center}

We can rotate the image using the usual graphicx controls, as below, or we can
use \cs{rotatebox}.

\begin{center}
\insertEPS[width=1in,angle=45]{myBestPic}\\
\small\verb!\insertEPS[width=1in,angle=45]{myBestPic}!
\end{center}

Any of the keys of \cs{includegraphics} can be used to manipulate
the image. The images can also be manipulated using other graphicx
commands, \cs{resizebox}, \cs{scalebox} and \cs{rotatebox}, for
example.

Finally, here is an example of the use of \texttt{presp} and \texttt{postsp}:

\def\mypreSP#1{%
    newpath
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    clip
    newpath
}
\def\mypostSP#1{%
    gsave
    [ /ca .4 /SetTransparency pdfmark
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    0.4 0.7 1 setrgbcolor
    fill
    grestore
    gsave
    [ /CA .5 /BM/Screen /SetTransparency pdfmark
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    40 setlinewidth
    0.4 0.7 1 setrgbcolor
    stroke
    grestore
}

\begin{center}
\includegraphics[name=myBestPic,width=1.5in,
    presp={\mypreSP{myBestPic}},
    postsp={\mypostSP{myBestPic}}]{myBestPic}
\end{center}
The \texttt{presp} code is

\begin{Verbatim}[fontsize=\small]
\def\mypreSP#1{%
    newpath
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    clip
    newpath
}
\end{Verbatim}
and clips the image in the shape of an ellipse. In this case, the
image is almost square, so the image is almost circular.

The \texttt{postsp} is

\begin{Verbatim}
\def\mypostSP#1{%
    gsave
    [ /ca .4 /SetTransparency pdfmark
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    0.4 0.7 1 setrgbcolor
    fill
    grestore
    gsave
    [ /CA .5 /BM/Screen /SetTransparency pdfmark
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    \widthOf{#1} 2 div \heightOf{#1} 2 div
    Draw_Ellipse
    40 setlinewidth
    0.4 0.7 1 setrgbcolor
    stroke
    grestore
}
\end{Verbatim}
After clipping the image itself, and displaying the image, we then
cover the image with an ellipse the same size, set the transparency
to 40\% opacity and fill, giving the image a bluish haze. Next, draw
the ellipse again and stroke it with a line 40 points wide. Give it an
opacity of 50\%, so \texttt{AdobeDon} will shine through.


\section{Special techniques for form appearances}\label{forms}

In addition to using embedded graphics to display an image with
\cs{includegraphics} or \cs{insertEPS}, these images can be
used as appearances for form fields. Examples of a push button and
checkbox can be found in the demo files, here reproduce the push
button example.

For this techniques, the eforms package is required. The forum
support of hyperref may not support the \textbf{AP} key the way
eforms does.

In the preamble, we have
\begin{Verbatim}
\begin{createImage}{\bboxOf{myBestPic}}{nAdobeDon}
    [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{\bboxOf{myBestPic}}{rAdobeDon}
    [ /ca .5 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}

\begin{createImage}{\bboxOf{myBestPic}}{dAdobeDon}
    [ /ca .3 /SetTransparency pdfmark
    [ {myBestPic} /SP pdfmark
\end{createImage}
\end{Verbatim}

We use \cs{bboxOf} to set the bounding boxes to be the same as the
original \texttt{myBestPic} image, and define a normal, rollover and
down appearances for the button (\texttt{nAdobeDon},
\texttt{rAdobeDon} and \texttt{dAdobeDon}), respectively. We use
various opacity settings for the appearances.

The button code is

\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\resizebox{.5in}{!}{\pushButton[\BC{}\BG{}\S{S}
  \A{\JS{app.alert("AcroTeX rocks the world!"); this.dirty=false;}}
  \autoCenter{y}\TP{1}\FB{true}
  \I{nAdobeDon}\IX{dAdobeDon}\RI{rAdobeDon}
]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}}
\end{Verbatim}
See the \pkg{eforms} manual for details of these key-value pairs.\smallskip

Finally, the button looks like this: \resizebox{.5in}{!}{\pushButton[%
    \autoCenter{y}\BC{}\BG{}\S{S}
    \A{\JS{app.alert("AcroTeX rocks the world!");this.dirty=false;}}
    \I{nAdobeDon}\IX{dAdobeDon}\RI{rAdobeDon}\TP{1}\FB{true}
]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}}\par\smallskip\noindent
In light of the discussion following display~\eqref{createImg} on page~\pageref*{createImg}, the code for the above
button could have been,
\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small]
\resizebox{.5in}{!}{\pushButton[\BC{}\BG{}\S{S}
  \A{\JS{app.alert("AcroTeX rocks the world!"); this.dirty=false;}}
  \autoCenter{y}\TP{1}\FB{true}
  \I{\nAdobeDon}\IX{\dAdobeDon}\RI{\rAdobeDon}
]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}}
\end{Verbatim}
When using \textbf{SP} images for form fields in this way, the images
\textbf{must always pass} through a \texttt{createImage} environment where the
bounding boxes can be precisely set, in the verbatim listing above,
note \verb!\bboxOf{myBestPic}! sets the bounding box. The reason you
can't use an embedded image directly is that the embedded image has
had its bounding box reset to an enormous value. See the
documentation in graphicxsp.dtx for more details.

The dimensions of the push button are the last two arguments of the
\cs{pushButton} command and are set to \verb!\widthOf{myBestPic}bp!
and \verb!\heightOf{myBestPic}bp!, (Note the use of the \texttt{bp}
dimension.)  We then resize this field using \cs{resizebox}! Very
swave how the graphicx and \pkg{GraphicxSP} work together.

\section{Tips}

Since you are using distiller, you have Acrobat as well. Try using
the PDF Optimizer (\texttt{Advanced > PDF Optimizer} menu) to
further reduce the size of the file. If you have Acrobat Pro 8.0,
you can do a Save As, by selecting Adobe PDF Files, Optimized from
the Save as type list. This is the same as using the PDF Optimizer.

An example of the savings is this manual, after distillation
document size was 176.6 KB, after the PDF Optimizer was done, the
file size was 113.6 KB. That's a reduction of 63 KB or that's a
reduction of 38\,\%. For some of the demo files, the reduction is
much more dramatic since the images are used and re-used many more
times than in this document.


\section{\texorpdfstring{\protect\pkg{GraphicxSP}}{GraphicxSP} example files}

The example files can be found in the \texttt{examples} folder of the \pkg{GraphicxSP}
distribution. They are
\begin{itemize}
\item \texttt{grxsp\_tst\_noaeb.tex}: General test file demonstrating SP graphics,
    does not require AeB (Acro\negthinspace\TeX{} eDucation Bundle).
\item \texttt{grxsp\_tst\_aeb.tex}: Same as previous file, but using AeB.
\item \texttt{grxsp\_comp\_noaeb.tex}: A comparison between graphicx \cs{includegraphics}
    and SP graphics. AeB not used.
\item \texttt{grxsp\_comp\_aeb.tex}: Same as previous file, but AeB is used.
\item \texttt{grxsp\_forms\_aeb.tex}: This file demonstrates using SP graphics as appearances
    of form fields. AeB required.
\item \texttt{grxsp\_layers\_aebpro.tex}: Demonstrates the use of SP graphics with
    Optional Content Groups, or layers. AeB Pro required.
\end{itemize}

\noindent
That's all for now, I simply must get back to my retirement. \dps

\end{document}