akfavatar-graphic(3)                                      akfavatar-graphic(3)



NNAAMMEE
       akfavatar-graphic  - Modul für die Anzeige von Grafiken unter Lua-AKFA‐
       vatar

SSYYNNTTAAXX
       local graphic = require "akfavatar-graphic"

BBEESSCCHHRREEIIBBUUNNGG
       Modul für Lua-AKFAvatar um Grafiken anzuzeigen.

       HHiinnwweeiissee:

       – Koordinaten fangen mit 1, 1 in der oberen linken Ecke an.

       – Man kann es auch nach Art der Turtle-Grafik verwenden.

       – Die Stiftbreite, Position, Ausrichtung, Stiftfarbe  und  Hintergrund‐
         farbe sind für jede Grafik einzeln festgelegt.

       – Der Code ist nicht auf Geschwindigkeit optimiert.  Man kann zwar Ani‐
         mationen machen, aber es werden keine fließenden Bewegungen.

   FFuunnkkttiioonneenn // MMeetthhooddeenn
       ggrraapphhiicc..nneeww((_[_B_r_e_i_t_e_, _H_ö_h_e_] _[_, _H_i_n_t_e_r_g_r_u_n_d_f_a_r_b_e_]))
              Erzeugt eine neue Grafik (eine Leinwand).

              Wenn die _B_r_e_i_t_e und _H_ö_h_e nicht angegeben wird, wird das  gesamte
              Fenster bzw. Bildschirm verwendet.
              Es  wird ein dünner, schwarzer Stift ausgewählt und die Position
              ist in der Mitte, nach oben ausgerichtet.
              Wenn die _H_i_n_t_e_r_g_r_u_n_d_f_a_r_b_e nicht angegeben ist,  wird  diese  von
              AKFAvatar übernommen.

              Gibt die Grafik, die Breite und Höhe zurück (dh. drei Werte).

              Beispiel:
              local gr, width, height = graphic.new()

       ggrraapphhiicc..ffuullllssiizzee(())
              Gibt  die erforderliche Breite und Höhe zurück, so dass das Bild
              das gesamte Fenster füllt.

       ggrraapphhiicc..sseett__rreessiizzee__kkeeyy((_T_a_s_t_e))
              Setzt einen Tasten-Code (als Zahl), die ausgegeben werden  soll,
              wenn die Fenstergröße verändert wurde.  Gibt den vorherigen Tas‐
              ten-Code zurück.

              HHiinnwweeiiss:: Man kann einen Wert zwischen 0xE000 und 0xE9FF  verwen‐
              den, um Konflikte mit echten Tasten-Codes zu vermeiden.

       ggrraapphhiicc..sseett__ppooiinntteerr__bbuuttttoonnss__kkeeyy((_T_a_s_t_e))
              Setzt  einen Tasten-Code (als Zahl), die ausgegeben werden soll,
              wenn eine Maustaste gedrückt wurde.  Gibt den vorherigen Tasten-
              Code zurück.

              HHiinnwweeiiss::  Man kann einen Wert zwischen 0xE000 und 0xE9FF verwen‐
              den, um Konflikte mit echten Tasten-Codes zu vermeiden.

       ggrraapphhiicc..sseett__ppooiinntteerr__mmoottiioonn__kkeeyy((_T_a_s_t_e))
              Setzt eine Tasten-Code (als Zahl), die ausgegeben  werden  soll,
              wenn  die  Maus  bewegt  wurde.  Gibt den vorherigen Tasten-Code
              zurück.

       ggrraapphhiicc..ggeett__ppooiinntteerr__ppoossiittiioonn(())
              Gibt die x und y Koordinaten der Maus-Position  zurück,  relativ
              zur zuletzt gezeigten Grafik.

       _g_r::sshhooww(())
              Zeigt die Grafik als Bild nach dem Zeichnen.

              HHiinnwweeiiss:  Man  kann  auch  Zwischenschritte  zeigen, dann weiter
              zeichnen, eine Weile warten und dann den nächsten Schritt zeigen
              und  so weiter.  Dadurch erzeugt man eine kleine Animation.  Man
              sollte die Schritte aber nicht zu klein wählen, sonst wird es zu
              langsam auf langsamen Geräten.

       _g_r::ssiizzee(())
              Gibt die Breite und Höhe der Grafik _g_r zurück.

       _g_r::wwiiddtthh(())
              Gibt die Breite der Grafik _g_r zurück.

       _g_r::hheeiigghhtt(())
              Gibt die Höhe der Grafik _g_r zurück.

       _g_r::ccoolloorr((_F_a_r_b_n_a_m_e))
              Legt die Zeichenfarbe fest.
              Die  Farbe  kann  entweder ein vordefinierter englischsprachiger
              Name sein, oder  eine  hexadezimale  Angabe,  wie  zum  Beispiel
              _0_x_F_F_F_F_0_0 oder _"_#_F_F_F_F_0_0_".

       _g_r::rrggbb((_r_o_t_, _g_r_ü_n_, _b_l_a_u))
              Legt die Zeichenfarbe anhand von RGB-Werten fest.
              Die Werte müssen im Bereich von 0 bis 255 inklusive sein.
              Diese Methode ist schneller, als ggrr::ccoolloorr(()) zu verwenden.

       _g_r::eerraasseerr(())
              Setzt die Zeichenfarbe auf die Hintergrundfarbe (Radiergummi).

       _g_r::tthhiicckknneessss((_W_e_r_t))
              Legt die Dicke des Stiftes fest.  Der _W_e_r_t 1 ist der dünnste.

       _g_r::cclleeaarr((_[_F_a_r_b_e_]))
              Löscht die Grafik.
              Wenn eine _F_a_r_b_e angegeben ist, wird diese zur neuen Hintergrund‐
              farbe.
              Die Stift-Position wird nicht verändert.

       _g_r::bboorrddeerr33dd((_[_g_e_d_r_ü_c_k_t_]))
              Zeichnet einen 3D-Rahmen um die Grafik.  Die Farbe  basiert  auf
              der  Hintergrundfarbe  der  Grafik.   Die Einstellung der Stift-
              Dicke wird ignoriert, der Rahmen ist immer 3 Pixel dick.

              Wenn _g_e_d_r_ü_c_k_t auf ttrruuee gesetzt wird, wird der Rahmen nach  innen
              gedrückt dargestellt.

              Die Stift-Position wird nicht verändert.

       _g_r::ppuuttppiixxeell((_[_x_, _y_]))
              Setzt  einen  Pixel an den angegebenen Koordinaten, oder bei der
              aktuellen Stift-Position.
              Die Stift-Position wird nicht verändert.

       _g_r::ggeettppiixxeell((_[_x_, _y_]))
              Gibt die Pixelfarbe an den angegebenen Koordinaten oder bei  der
              aktuellen  Stift-Position  zurück.  Die Farbe wird als String in
              hexadezimaler  RGB-Schreibweise  zurückgegeben.   Im  Fehlerfall
              wird _n_i_l und eine Fehlermeldung zurückgegeben.
              Die Stift-Position wird nicht verändert.

       _g_r::ggeettppiixxeellrrggbb((_[_x_, _y_]))
              Gibt  die Pixelfarbe an den angegebenen Koordinaten oder bei der
              aktuellen Stift-Position zurück.
              Es werden drei Ganzzahlen für rot, grün und blau, im Bereich von
              0 bis 255 zurückgegeben.
              Im Fehlerfall wird _n_i_l und eine Fehlermeldung zurückgegeben.
              Die Stift-Position wird nicht verändert.

       _g_r::ppuuttddoott((_[_x_, _y_]))
              Setzt  einen  Punkt an den angegebenen Koordinaten, oder bei der
              aktuellen Stift-Position.
              Wenn der Stift dünn ist, ist es das gleiche wie ggrr::ppuuttppiixxeell(()).
              Die Stift-Position wird nicht verändert.

       _g_r::ppeenn__ppoossiittiioonn(())
              Gibt die x- und y-Position des Stiftes  zurück  (dh.  es  werden
              zwei Werte zurückgegeben).

       _g_r::cceenntteerr(())
       _g_r::hhoommee(())
              Setzt  den  Stift  auf  die  Mitte  der  Grafik,  nach oben aus‐
              gerichtet.

       _g_r::mmoovveettoo((_x_, _y))
              Bewegt den Stift nach _x_, _y ohne zu zeichnen.

       _g_r::mmoovveerreell((_x_, _y))
              Bewegt den Stift ohne zu zeichnen relativ  zu  seiner  aktuellen
              Position.
              Ein postitiver _x-Wert bewegt ihn nach rechts,
              ein negativer _x-Wert bewegt ihn nach links.
              Ein postitiver _y-Wert bewegt ihn nach unten,
              ein negativer _y-Wert bewegt ihn nach oben.

       _g_r::lliinneettoo((_x_, _y))
              Zeichnet  eine  Linie  von  der  aktuellen Stift-Position zu den
              absoluten Koordinaten.
              Der Stift wird zu den neuen Koordinaten bewegt.

       _g_r::lliinneerreell((_x_, _y))
              Zeichnet eine Linie relativ zur aktuellen Stift-Position.
              Ein postitiver _x-Wert zeichnet nach rechts,
              ein negativer _x-Wert zeichnet nach links.
              Ein postitiver _y-Wert zeichnet nach unten,
              ein negativer _y-Wert zeichnet nach oben.
              Der Stift wird dabei zu den neuen Koordinaten bewegt.

       _g_r::lliinnee((_x_1_, _y_1_, _x_2_, _y_2))
              Zeichnet eine Linie von _x_1_, _y_1 nach _x_2_, _y_2.
              Der Stift wird auf _x_2_, _y_2 gesetzt.

       _g_r::bbaarr((_x_1_, _y_1_, _x_2_, _y_2))
              Malt einen ausgefüllten Balken mit _x_1_, _y_1 als obere  linke  Ecke
              und _x_2_, _y_2 als untere rechte Ecke.
              Die Stift-Position wird nicht verändert.

       _g_r::rreeccttaannggllee((_x_1_, _y_1_, _x_2_, _y_2))
              Zeichnet ein Rechteck mit _x_1_, _y_1 als obere linke Ecke und _x_2_, _y_2
              als untere rechte Ecke.
              Die Stift-Position wird nicht verändert.

       _g_r::aarrcc((_R_a_d_i_u_s _[_, _W_i_n_k_e_l_1_] _[_, _W_i_n_k_e_l_2_]))
       _g_r::cciirrccllee((_R_a_d_i_u_s _[_, _W_i_n_k_e_l_1_] _[_, _W_i_n_k_e_l_2_]))
              Zeichnet einen Kreis oder Bogen mit dem angegebenen _R_a_d_i_u_s.
              Die Stift-Position markiert den Mittelpunkt.

              Man kann einen Teil des Kreises (einen  Bogen)  zeichnen,  indem
              man  einen  oder  zwei  Winkel in Grad angibt.  Wenn zwei Winkel
              angegeben sind, dann wird im Uhrzeigersinn vom ersten Winkel bis
              zum  zweiten  gezeichnet.   Wenn  nur ein Winkel angegebene ist,
              verwendet es  die  Stift-Ausrichtung  als  Anfangswinkel  (siehe
              unten bei TTuurrttllee--GGrraaffiikk).

       _g_r::ddiisscc((_R_a_d_i_u_s _[_, _x_, _y_]))
              Zeichnet  eine  Scheibe,  dh.  einen  gefüllten  Kreis  mit  dem
              angegebenen _R_a_d_i_u_s und  den  angegebenen  Koordinaten  als  Mit‐
              telpunkt.   Sind  keine Koordinaten angegeben, wird die aktuelle
              Stift-Position als Mittelpunkt verwendet.
              Die Stift-Position wird nicht verändert.

       _g_r::tteexxtt((_T_e_x_t _[_, _x_, _y_]))
              Schreibt einen Text, ausgerichtet an  der  angegebenen  Position
              oder der Stift-Position.

              Standardmäßig  wird der Text an der Postion zentriert.  Aber das
              kann man mit ggrr::tteexxttaalliiggnn(()) ändern.

              Die Kodierung wird von den  AKFAvatar-Einstellungen  übernommen.
              Andererseits  werden  keine  anderen  der dortigen Einstellungen
              verwendet.  Die Farbe ist die Zeichenfarbe für die  Grafik.   Es
              gibt  momentan  keine einfache Möglichkeit für Fettdruck, Unter‐
              streichen oder inverse Dastellung.

              Man  kann  sämtliche  darstellbaren  Zeichen   verwenden,   aber
              Steuerzeichen  werden  nicht unterstützt, nichtmal ein Zeilenum‐
              bruch.
              Die Stift-Position wird nicht verändert.

       _g_r::tteexxttaalliiggnn((_[_h_o_r_i_z_o_n_t_a_l_] _[_, _v_e_r_t_i_k_a_l_]))
              Legt die Ausrichtung für ggrr::tteexxtt(()) fest.

              Die horizontale Ausrichtung kann eines von "left", "center" oder
              "right" sein.  Die Vorgabe ist "center".

              Die  vertikale  Ausrichtung  kann eines von "top", "center" oder
              "bottom" sein.  Die Vorgabe ist "center".

              Die Ausrichtung bedeutet, wo der Bezugspunkt ist,  zum  Beispiel
              wenn  man  angibt, dass es links ausgerichtet sein soll, ist der
              Bezugspunkt links, aber der Text läuft nach rechts.

       ggrraapphhiicc..ffoonntt__ssiizzee(())
       _g_r::ffoonntt__ssiizzee(())
              Gibt die Breite, Höhe und die Grundlinie eines Zeichens  zurück.
              Es  handelt  sich  um einen Zeichensatz mit fester Breite, jedes
              Zeichen hat die selbe Breite.

       _g_r::ppuutt((_G_r_a_f_i_k _[_, _x_, _y_]))
              Kopiert eine Grafik auf die Grafik _g_r bei der angegebenen  Posi‐
              tion  (obere  linke  Ecke).   Wenn keine Position angegeben ist,
              wird es in die obere linke Ecke gesetzt.  Der  vorherige  Inhalt
              wird überschrieben (keine Transparenz).

              Eine Grafik mit der selben Breite und ohne Angabe einer Position
              zu kopieren ist äußerst effizient.   Das  selbe  gilt  wenn  die
              Grafik  die  selbe  Breite  hat und die _x-Position auf 1 gesetzt
              ist.

       _g_r::ppuutt__ttrraannssppaarreennccyy((_G_r_a_f_i_k _[_, _x_, _y_]))
              Legt eine Grafik über die Grafik _g_r bei der angegebenen Position
              (obere linke Ecke).
              Wenn  keine  Position  angegeben ist, wird es in die obere linke
              Ecke gesetzt.
              Pixel mit der Hintergrundfarbe werden nicht  kopiert,  die  sind
              transparent.
              Dies ist wesentlich langsamer als ggrr::ppuutt(()).

       _g_r::ppuutt__ffiillee((_D_a_t_e_i_n_a_m_e _[_, _x_, _y_]))
              Kopiert  eine  Grafik  aus einer Datei auf die Grafik _g_r bei der
              angegebenen Position (obere linke Ecke).
              Wenn keine Position angegeben ist, wird es in  die  obere  linke
              Ecke gesetzt.

       _g_r::ppuutt__iimmaaggee((_D_a_t_e_n _[_, _x_, _y_]))
              Kopiert  eine  Grafik  aus  den  _D_a_t_e_n auf die Grafik _g_r bei der
              angegebenen Position (obere linke Ecke).  _D_a_t_e_n kann ein  String
              mit  den  Bilddaten sein, oder eine Tabelle mit Strings von XPM-
              Daten.
              Wenn keine Position angegeben ist, wird es in  die  obere  linke
              Ecke gesetzt.

       _g_r::ggeett((_x_1_, _y_1_, _x_2_, _y_2))
              Gibt einen Bereich der Grafik _g_r als neue Grafik zurück.
              Die meisten Einstellungen werden ebenfalls kopiert, mit Ausnahme
              der Größe und der Stift-Position.
              Der Stift wird auf die Mitte der neuen Grafik gesetzt, nach oben
              ausgerichtet.
              Alle Werte müssen im gültigen Bereich liegen.

       _g_r::dduupplliiccaattee(())
              Gibt ein exaktes Duplikat (eine Kopie) der Grafik _g_r zurück.
              Die Grafik-spezifischen Einstellungen werden ebenfalls kopiert.
              Das geht schneller als mit ggrr::ggeett(()).

              Man  kann  dies  zum Beispiel verwenden, um erstmal einen festen
              Hintergrund zu zeichnen und  dann  ein  Duplikat  zu  erstellen.
              Darauf  zeichnet  man dann einen Vordergrund.  Dann kann man den
              Hintergrund wieder darauf  kopieren  (ggrr::ppuutt)  und  einen  neuen
              Vordergrund zeichnen.

       _g_r::sshhiifftt__vveerrttiiccaallllyy((_Z_e_i_l_e_n))
              Verschiebt die Grafik vertikal.
              Ein positiver Wert für _Z_e_i_l_e_n schiebt sie nach unten.
              Ein negativer Wert für _Z_e_i_l_e_n schiebt sie nach oben.
              Der Stift wird mitbewegt.

       _g_r::sshhiifftt__hhoorriizzoonnttaallllyy((_S_p_a_l_t_e_n))
              Verschiebt die Grafik horizontal.
              Ein positiver Wert für _S_p_a_l_t_e_n schiebt sie nach rechts.
              Ein negativer Wert für _S_p_a_l_t_e_n schiebt sie nach links.
              Der Stift wird mitbewegt.

       _g_r::eexxppoorrtt__ppppmm((_f_i_l_e_n_a_m_e))
              Exportiert die Grafik als Portable Pixmap (PPM) Datei.

              Das  PPM-Format  ist  simpel  zu implementieren, aber nicht sehr
              effizient.  Man kann aber die „netpbm“-Werkzeuge oder „ImageMag‐
              ick“ verwenden, um es in ein anderes Format umzuwandeln.

              Das folgende Beispiel zeigt, wie man das macht:

              function export(graphic, name)
                graphic:export_ppm(name..".ppm")
                if os.execute("pnmtopng "..name..".ppm > "..name..".png")
                   or os.execute("convert "..name..".ppm "..name..".png") then
                  os.remove(name..".ppm")
                end
              end

              Zunächst exportiert es die Grafik ins PPM-Format.  Dann versucht
              es dieses ins PNG-Format umzuwandeln.  Falls das  gelingt,  wird
              die   PPM-Datei  gelöscht.   Wenn  der  Anwender  „netpbm“  oder
              „ImageMagick“ aber nicht installiert hat, hat er am  Ende  immer
              noch die PPM-Datei.

   TTuurrttllee--GGrraaffiikk
       Um  Turtle-Grafik  („Schildkröten-Grafik“,  manchmal auch „Igel-Grafik“
       genannt) zu verstehen, muss man sich eine Schildkröte  verstellen,  die
       einen  Stift  trägt.  Man kann der Schildkröte dann Befehle erteilen in
       welche Richtung sie sich drehen soll und wie weit sie sich  zu  bewegen
       hat.

       _g_r::hheeaaddiinngg((_A_u_s_r_i_c_h_t_u_n_g))
              Legt  die  Ausrichtung  der  Schildkröte fest.  Der Wert muss in
              Grad  angegeben  werden  und  die  Schildkröte  dreht  sich   im
              Uhrzeigersinn.   Der  Wert  0  bedeutet,  sie ist nach oben aus‐
              gerichtet, 90 bedeutet nach rechts.

       _g_r::ggeett__hheeaaddiinngg(())
              Gibt die Ausrichtung  der  Schildkröte  zurück  (siehe  ggrr::hheeaadd‐‐
              iinngg(())).

       _g_r::rriigghhtt((_W_i_n_k_e_l))
              Drehe die Schildkröte im Uhrzeigersinn um den angegebenen _W_i_n_k_e_l
              in Grad.

       _g_r::lleefftt((_W_i_n_k_e_l))
              Drehe die Schildkröte gegen den Uhrzeigersinn um den angegebenen
              _W_i_n_k_e_l in Grad.

       _g_r::ddrraaww((_S_c_h_r_i_t_t_e))
              Zeichne  eine  Linie in die Richtung, in die die Schildköte aus‐
              gerichtet ist.

       _g_r::mmoovvee((_S_c_h_r_i_t_t_e))
              Bewege die Schildkröte in die Richtung in der  sie  ausgerichtet
              ist, ohne zu zeichnen.

       _g_r::hhoommee(())
              Setzt  die  Schildkröte  in die Mitte der Grafik, nach oben aus‐
              gerichtet.

SSIIEEHHEE AAUUCCHH
       lluuaa--aakkffaavvaattaarr(1) lluuaa(1)  lluuaa--aakkffaavvaattaarr--rreeff(3)  aakkffaavvaattaarr--tteerrmm(3)  aakkffaa‐‐
       vvaattaarr..uuttff88(3)



AKFAvatar                         2013-08-09              akfavatar-graphic(3)
