Debian Codegraph @

texmf-dist/doc/latex/pixelart/pixelart0.tex

raw
1 \documentclass{ltxdoc}
2
3 \RecordChanges
4
5 \usepackage{hyperref}
6 \usepackage{pixelart0}
7 \usepackage{numprint}
8 \usepackage{mdframed}
9
10 \usepackage{listings}
11 \lstset{
12 language=[LaTeX]TeX,
13 numbers=left,
14 numberstyle=\tiny,
15 backgroundcolor=\color{yellow!20},
16 basicstyle=\small\color{black}\ttfamily,
17 keywordstyle=\color{blue!80}\sffamily,
18 commentstyle=\color{olive},
19 stringstyle=\color{red},
20 }
21
22 \usepackage{textcomp}
23 \usepackage{fontspec}
24 \usepackage[english]{babel}
25
26 \usepackage{manfnt}
27
28 \begin{document}
29
30 \CheckSum{0}
31 \CharacterTable
32 {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
33 Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
34 Digits \0\1\2\3\4\5\6\7\8\9
35 Exclamation \! Double quote \" Hash (number) \#
36 Dollar \$ Percent \% Ampersand \&
37 Acute accent \' Left paren \( Right paren \)
38 Asterisk \* Plus \+ Comma \,
39 Minus \- Point \. Solidus \/
40 Colon \: Semicolon \; Less than \<
41 Equals \= Greater than \> Question mark \?
42 Commercial at \@ Left bracket \[ Backslash \\
43 Right bracket \] Circumflex \^ Underscore \_
44 Grave accent \` Left brace \{ Vertical bar \|
45 Right brace \} Tilde \~}
46
47 \GetFileInfo{pixelart0.dtx}
48
49 \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ ,\!,\(,\),\,}
50 \DoNotIndex{\@bwpa@newline}
51 \DoNotIndex{\begin}
52 \DoNotIndex{\coordinate}
53 \DoNotIndex{\end, \else}
54 \DoNotIndex{\fill, \fi}
55 \DoNotIndex{\ifpixelart@draft}
56 \DoNotIndex{\makeatletter, \makeatother}
57 \DoNotIndex{\newcommand, \newif}
58 \DoNotIndex{\ProcessPgfPackageOptions, \pgfkeys, \pgfkeyssetvalue, \pgfkeysvalueof, \pgfparserdef, \pgfparserparse, \pgfparserswitch}
59 \DoNotIndex{\raisebox, \RequirePackage}
60 \DoNotIndex{\space}
61 \DoNotIndex{\tikz}
62 \DoNotIndex{\usepgfmodule, \usetikzlibrary}
63
64 \title{
65 \begin{tikzpicture}
66 \tikzbwpixelart[scale=.037]{(-1.05, .14)}{%
67 111111000110000000000000000000111000001000000000000000100000011100
68 011001100110000000000000000000011000011100000000000001100000100010
69 011001100000000000000000000000011000110110000000000001100001100111
70 011001101110011000011001111100011001100011011011100111111001100111
71 011111000110001100110011000110011001100011001110110001100001101011
72 011000000110000111100011111110011001111111001100110001100001101011
73 011000000110000011000011000000011001100011001100000001100001110011
74 011000000110000111100011000000011001100011001100000001100001110011
75 011000000110001100110011000110011001100011001100000001101100100010
76 111100001111011000011001111100111101100011011110000000111000011100
77 }%
78 \draw (0, 0) node[opacity=0]{\LARGE PixelArt0};
79 \end{tikzpicture}\thanks{
80 This document corresponds to \textsf{pixelart0}~0.3.0, dated 2022-11-16.
81 Home page, bug requests, etc. at \url{http://framagit.org/spalax/pixelart}
82 }\\A package to draw pixel-art pictures.}
83 \author{Louis Paternault\\ \texttt{spalax(at)gresille(dot)org}}
84
85 \maketitle
86
87 \begin{abstract}
88 This package defines macros to draw pixel-art pictures using \LaTeX{}.
89 \end{abstract}
90
91 \changes{v0.3.0}{2022/10/23}{Rename \textsf{pixelart} to \textsf{pixelart0}.}
92 \begin{mdframed}
93 \textbf{\textdbend Warning :} This package is an outdated version of \textsf{pixelart}, that works with \LaTeX (while \textsf{pixelart} requires Lua\LaTeX). It is kept around for background compatibility.
94 \begin{itemize}
95 \item If you are a new user:
96 \begin{itemize}
97 \item if you are using Lua\LaTeX, you can use \textsf{pixelart} version 1.0.0 or later;
98 \item otherwise, you can use the \textsf{pxpic} package, by Jonathan P. Spratte.
99 \end{itemize}
100 \item if you did use \textsf{pixelart} before version 1.0.0, you are advised to switch to \textsf{pixelart} version 1.0.0 or later, or to switch to \textsf{pxpic} (see above). Or you can replace your \lstinline|\requirepackage{pixelart}| by \lstinline|\requirepackage{pixelart0}| to continue using this outdated version.
101 \end{itemize}
102 \end{mdframed}
103
104 \setcounter{tocdepth}{2}
105 \tableofcontents
106
107 \section{Introduction}
108 This document introduces the \textsf{pixelart0} package, used to draw pixel-art pictures.
109
110 It is an outdated version of \textsf{pixelart} (before version 1.0.0), kept as part of \textsf{pixelart} for backward compatibility.
111
112 \subsection{License}
113 This work may be distributed and/or modified under the
114 conditions of the \LaTeX Project Public License, either version 1.3
115 of this license or (at your option) any later version.
116
117 Further information can be found in the |.dtx| file used to build this
118 document.
119
120 \subsection{Overview}
121 Installation instruction are given in section \ref{sec:install}.
122 Documentation about how to use this package (and examples) is given in section
123 \ref{sec:usage}. Section \ref{sec:bugs} lists some known bugs and
124 limitations.
125
126 \section{Download and Install}
127 \label{sec:install}
128
129 \subsection{\textsc{Gnu}/Linux Distribution}
130
131 If applicable, the easiest way to get |pixelart0| working is by installing it by your distribution package. In Debian (and Ubuntu, and surely other distributions that inherit from Debian) it is packaged in |texlive-pictures| since version \texttt{2017.20180103-1}. So you can install it by running:
132
133 \begin{quote}
134 |sudo apt install texlive-pictures|
135 \end{quote}
136
137 \subsection{LaTeX distribution}
138
139 This package is included both in \TeX{}Live and MiK\TeX{}, as part of \textsf{pixelart}. It can be installed using their respective package managers.
140
141 \subsection{Manual installation}
142
143 \begin{itemize}
144 \item Download the lastest archive :
145 \begin{description}
146 \item[Stable version] \url{https://mirrors.ctan.org/graphics/pgf/contrib/pixelart.zip}
147 \item[Development version] \url{https://framagit.org/spalax/pixelart/repository/archive.zip?ref=main}
148 \end{description}
149 \item Unzip the archive.
150 \item If you got the archive from CTAN (stable version), move file \texttt{tex/latex/pixelart/pixelart0.sty} in a \LaTeX{} path.
151 \item If you got the development version, move the \texttt{pixelart0.sty} file into a \LaTeX{} path.
152 \end{itemize}
153
154 \section{Usage}
155 \label{sec:usage}
156
157 \subsection{Package options}
158 \changes{v0.2.0}{2018/02/25}{Add package option \texttt{draft}.}
159
160 This package has a single package option: |draft|. If this option is set (\lstinline|\usepackage[draft]{pixelart}|), pixel-art pictures are ignored. This can make compilation \emph{way, way} faster\footnote{On a document I am writing, containing a lot of pixel-art pictures, option |draft| makes compilation time go from 6 minutes to 22 seconds.}.
161
162 A downside is that since pixel-art pictures are ignored, this can mess up your document layout. A nicer option would be to have option |draft| guess the pixel-art size, and display a dummy picture with the same size\footnote{This has been implemented in |pixelart|.}.
163
164 \subsection{Macros}
165
166 This package defines two macros : |\bwpixelart|\footnote{\texttt{$\backslash{}$bwpixelart} stands for \emph{b}lack and \emph{w}hite \emph{pixel art}, although \emph{color and transparent pixel art} would be more accurate.}, used to insert a pixel-art picture, and |\tikzbwpixelart|, which has the same purpose, excepted that it is called from within a |tikzpicture| environment.
167 \changes{v0.1.2}{2018/01/13}{First line-break of pixelart argument is now automatically ignored.}
168
169 \subsubsection{\textbackslash\texttt{bwpixelart}}
170 \DescribeMacro{\bwpixelart}
171 To insert a pixel-art picture in your text, use :
172 \begin{center}
173 \lstinline|\bwpixelart|\oarg{color, raise, scale}\marg{pixels}
174 \end{center}
175 Its optional arguments are:
176 \begin{description}
177 \item[color=black] Foreground color (the background is transparent);
178 \item[scale=1] Scale. By default, a pixel is the size of a |tikzpicture| default unit, which is probably bigger than what you want.
179 \item[raise=0pt] Raise the picture. By default, the bottom of the picture is on the baseline. You might want to lower it a little by giving this option a negative argument.
180 \end{description}
181
182 Its mandatory argument is the picture pixels, as |0|'s and |1|'s. Line breaks in this argument are interpreted as line breaks in the pixel art pictures. How spaces are interpreted is undefined (see section \ref{ssec:spaces} for more information).
183
184 For instance, this heart
185 \bwpixelart[color=red, scale=.05, raise=-1ex]{%
186 001101100
187 011111110
188 111111111
189 111111111
190 111111111
191 011111110
192 001111100
193 000111000
194 000010000
195 }
196 was drawn using the following code:
197
198 \begin{lstlisting}
199 \bwpixelart[color=red, scale=.05, raise=-1ex]{%
200 001101100
201 011111110
202 111111111
203 111111111
204 111111111
205 011111110
206 001111100
207 000111000
208 000010000
209 }
210 \end{lstlisting}
211
212 \subsubsection{\textbackslash\texttt{tikzbwpixelart}}
213 \DescribeMacro{\tikzbwpixelart}
214 The second macro, |\tikzbwpixelart| is almost identical to the first one, excepted that it is meant to be called from inside a |tikzpicture| environment. Actually, \lstinline|\bwpixelart{0101}| is more or less equivalent to calling :
215
216 \begin{lstlisting}
217 \begin{tikzpicture}
218 \tikzbwpixelart{(0, 0)}{0101}
219 \end{tikzpicture}
220 \end{lstlisting}
221
222 The signature of this macro is :
223 \begin{center}
224 \lstinline|\tikzbwpixelart|\oarg{color, scale}\marg{coordinates}\marg{pixels}
225 \end{center}
226 Its optional arguments are |color| and |scale|, used to set the color and scale of the picture.
227
228 Its first mandatory argument is the coordinate of the top left corner of the picture; the second one is the list of pixels (using the same syntax as the |\bwpixelart| macro).
229
230 For instance, this heart
231 \begin{tikzpicture}[scale=.05, baseline=-1em]
232 \fill[red] (5, -4) circle (6.5);
233 \tikzbwpixelart{(0, 0)}{%
234 0011001100
235 0111111110
236 1111111111
237 1111111111
238 1111111111
239 0111111110
240 0011111100
241 0001111000
242 0000110000
243 }
244 \end{tikzpicture}
245 was drawn using the following code:
246
247 \begin{lstlisting}
248 \begin{tikzpicture}[scale=.05, baseline=-1em]
249 \fill[red] (5, -4) circle (6.5);
250 \tikzbwpixelart{(0, 0)}{%
251 0011001100
252 0111111110
253 1111111111
254 1111111111
255 1111111111
256 0111111110
257 0011111100
258 0001111000
259 0000110000
260 }
261 \end{tikzpicture}
262 \end{lstlisting}
263
264 \section{Bugs, Ideas, Undefined behaviours}
265 \label{sec:bugs}
266
267 \marginpar{Note that most of the stuff in this section have been fixed in the version 1.0.0 of \textsf{pixelart}.}
268 I have great ideas about what this package could do, but:
269 \begin{itemize}
270 \item I do not need them;
271 \item I am not sure there is a huge \emph{need} for some pixel-art package;
272 \item I have a full-time job, my wife has a far-more-than-full-time job, my daugther \emph{is} a full-time job\footnote{She has grown up, and I can get more sleep and more free time now, which explains |pixelart| version 1.0.0!}, so I have very little time to hack…
273 \end{itemize}
274
275 So, I am listing here some known bugs, undefined behaviours, limitations.
276
277 \subsection{Missing \texttt{\textbackslash{}pixelart} macro}
278
279 There is no |\pixelart| macro. This is on purpose: given that this package is more or less a working draft, I did not want to register a badly designed |\pixelart| macro. This means that some folk wanting to improve this package can extand the |\bwpixelart| macro and use the name |\pixelart| to fix my design mistakes.
280
281 \subsection{It's insanely slooooow.}
282
283 That's it. It takes alomst 30 seconds to compile a document containing only a $128\times128$ picture (about \numprint{16000} pixels). I have no idea how to fix it. Good luck.
284
285 \subsection{Black and white}
286
287 Right now, it is black and white only (or, to be more accurate, any single color on a transparent background).
288
289 One \emph{could} produce colored pixel-art pictures, but… it's complicated. For instance, this heart (borrowed from the Django project\footnote{\url{https://www.djangoproject.com/}}):
290
291 \definecolor{violet1}{RGB}{247, 176, 207}
292 \definecolor{violet2}{RGB}{238, 33, 120}
293 \definecolor{violet3}{RGB}{214, 45, 117}
294 \definecolor{violet4}{RGB}{217, 25, 92}
295 \definecolor{violet5}{RGB}{173, 29, 69}
296 \begin{center}
297 \begin{tikzpicture}[scale=.1]
298 \tikzbwpixelart[color=violet1]{(0, 0)}{%
299 0000000
300 0000010
301 }
302 \tikzbwpixelart[color=violet2]{(0, 0)}{%
303 0000000
304 0110100
305 0000000
306 0010100
307 0000000
308 0001000
309 }
310 \tikzbwpixelart[color=violet3]{(0, 0)}{%
311 0000010
312 0000000
313 1000010
314 0000000
315 0001000
316 }
317 \tikzbwpixelart[color=violet4]{(0, 0)}{%
318 0010100
319 1001000
320 0110100
321 0001010
322 0010100
323 }
324 \tikzbwpixelart[color=violet5]{(0, 0)}{%
325 0100000
326 0000001
327 0001001
328 0100000
329 }
330 \end{tikzpicture}
331 \end{center}
332
333 could be produced using the following code. Basically (given that colors |violet1| to |violet5| have been correctly defined), we stack up several single-color pixel-art pictures.
334
335 \begin{lstlisting}
336 \begin{tikzpicture}[scale=.1]
337 \tikzbwpixelart[color=violet1]{(0, 0)}{%
338 0000000
339 0000010
340 }
341 \tikzbwpixelart[color=violet2]{(0, 0)}{%
342 0000000
343 0110100
344 0000000
345 0010100
346 0000000
347 0001000
348 }
349 \tikzbwpixelart[color=violet3]{(0, 0)}{%
350 0000010
351 0000000
352 1000010
353 0000000
354 0001000
355 }
356 \tikzbwpixelart[color=violet4]{(0, 0)}{%
357 0010100
358 1001000
359 0110100
360 0001010
361 0010100
362 }
363 \tikzbwpixelart[color=violet5]{(0, 0)}{%
364 0100000
365 0000001
366 0001001
367 0100000
368 }
369 \end{tikzpicture}
370 \end{lstlisting}
371
372 One could imagine a simpler syntax: we assign several colors to characters, and we use |1|, |2|, |3|, etc. as the pixels to define the picture. This would give the following code.
373
374 \begin{lstlisting}
375 \begin{tikzpicture}[scale=.1]
376 \tikzpixelart[colors={
377 1=violet1,
378 2=violet2,
379 3=violet3,
380 4=violet4,
381 5=violet5,
382 }]{(0, 0)}{%
383 0540430
384 4224215
385 3445435
386 0524240
387 0043400
388 0002000
389 }
390 \end{tikzpicture}
391 \end{lstlisting}
392
393 \subsection{Spaces}
394 \label{ssec:spaces}
395
396 Spaces are interpreted as line breaks. For instance, this heart
397 \bwpixelart[scale=.03, raise=-1pt]{%
398 0011001100 0111111110 1111111111
399 1111111111 1111111111 0111111110
400 0011111100 0001111000 0000110000
401 }
402 could be written as :
403
404 \begin{lstlisting}
405 \bwpixelart[scale=.03, raise=-1pt]{%
406 0011001100 0111111110 1111111111
407 1111111111 1111111111 0111111110
408 0011111100 0001111000 0000110000
409 }
410 \end{lstlisting}
411
412 This will work (right now), but is an undefined behaviour, and might change in a later version without prior notice.
413
414 \subsection{Uneven lines}
415
416 Right now, lines do not \emph{have} to have the same number of characters. For instance, the following heart
417 \bwpixelart[scale=.03, raise=-1pt]{%
418 00110011
419 011111111
420 1111111111
421 1111111111
422 1111111111
423 011111111
424 00111111
425 0001111
426 000011
427 }
428 could be written as :
429
430 \begin{lstlisting}
431 \bwpixelart[scale=.03, raise=-1pt]{%
432 00110011
433 011111111
434 1111111111
435 1111111111
436 1111111111
437 011111111
438 00111111
439 0001111
440 000011
441 }
442 \end{lstlisting}
443
444 This is an undefined behaviour and might raise an error in the future.
445
446 \changes{v0.1.0}{2017/12/05}{First published version.}
447
448 \addcontentsline{toc}{section}{Change History}
449 \PrintChanges
450
451 \addcontentsline{toc}{section}{Index}
452 \PrintIndex
453
454 \end{document}