SSHAPE (BASIC 3.5)

SSHAPE (BASIC 3.5)
Syntax:	SSHAPE <Variable>, [<Koordinaten1> [, [<Koordinaten2>] ]
Parameter
<Variable>: Bezeichnung einer Zeichenkettenvariable
<Koordinaten1>: [+|-]<X1>,[+|-]<Y1> | <Strecke>;<Winkel>
<Koordinaten2>: [+|-]<X2>,[+|-]<Y2> | <Strecke>;<Winkel>
Einordnung
Typ:	Anweisung
Kontext:	Grafikanweisung
Aufgabe:	Einen rechteckigen Grafikausschnitt in eine Zeichenkettenvariable kopieren
Abkürzung:	sS
Token:	$e4 (228)
Verwandte Befehle
GSHAPE

Anmerkung: Dieser Artikel beschreibt den BASIC-Befehl SSHAPE ab Commodore BASIC V3.5 oder höher.

Die Anweisung SSHAPE (für engl. Save/Store SHAPE, auf deutsch: sichere oder speichere Form/Gebilde) kopiert einen rechteckigen Grafikausschnitt in eine Variable vom Typ einer Zeichenkette. Mittels GSHAPE kann der Ausschnitt später wieder in eine Grafik oder mit SPRSAV in ein Sprite (sofern unterstützt) hinein kopiert werden.

Die Anweisung kennt folgende Parameter:

1. Zeichenkettenvariable: Ist die Variable, die die Grafikdaten aufnimmt. Da eine Zeichenkettenvariable nur maximal 255 Zeichen aufnehmen kann, ist die Größe des Ausschnitts begrenzt. Zu große Ausschnitte rufen dann die Fehlermeldung ?STRING TOO LONG ERROR hervor.
   Maximal mögliche Ausdehnungen:
   • in X-Richtung:
     SSHAPE A$,0,0,2007,0
     entspricht einem 1 Pixel hohen mal 2008 Pixel breiten Rechteck.
   • in Y-Richtung:
     SSHAPE A$,0,0,7,250
     entspricht einem 251 Pixel hohen mal 8 Pixel breiten Rechteck.
2. Koordinaten1 (X1,Y1): Die erste Ecke des Ausschnitts.
3. Koordinaten2 (X2,Y2): Die zweite Ecke des Ausschnitts. Diese Angabe ist optional, voreingestellt ist die aktuelle Position des Pixel-Cursors.

Wie auch bei anderen Grafikbefehlen unter BASIC V3.5 können die Koordinaten absolut-kartesisch, relativ-kartesisch zum Pixel-Cursor oder als Vektor mit den Angaben Länge und Winkel relativ zum Pixel-Cursor angegeben werden. Kartesische Koordinaten werden in der Form X,Y angegeben, Vektor-Parameter dagegen in der Form Streckenlänge;Winkel. Die Winkelangabe erfolgt in Grad im Uhrzeigersinn, wobei 0 Grad senkrecht nach oben gerichtet bedeutet. Für relative Positionsangaben mit Variablen müssen diese in runden Klammern geschrieben werden. Der erlaubte Wertebereich für die Koordinaten reicht von -65535 bis +65535, wobei negative absolute Koordinaten über Variablen übergeben werden müssen (wie sinnvoll das auch immer sein mag). Werte außerhalb des erlaubten Bereiches führen zu einem ?ILLEGAL QUANTITY ERROR.
Die Reihenfolge, mit der die Eckkoordinaten angegeben werden (z.B links-oben/rechts-unten oder rechts-oben/links-unten), ist bedeutungslos.

Pro Pixel wird die aktive Farbquelle (Hintergrund, Vordergrund, Multicolor1/2) gespeichert, nicht aber die Farbe selbst. Befinden sich Teile des Shapes außerhalb des sichtbaren Bereichs, werden diese als Hintergrund interpretiert.

Datenformat

Die Daten werden zeilenweise in Segmenten von 8 Pixeln in der Zeichenkettenvariable abgelegt. Pro angefangenem Segment wird ein Zeichen belegt, dabei wird das erste Pixel in Bit 7 des Bytes abgebildet (bzw. Bit 6 und 7 im Multicolormodus), das zweite Pixel in Bit 6 (bzw. Bit 5 und 6) usw. Auf das Ende der Grafikdaten folgen noch Low-Byte/High-Byte der Shape-Breite minus 1 und Low-Byte/High-Byte der Shape-Höhe minus 1. Ein String der Länge L hat demnach folgenden Aufbau:

1. Byte	2. Byte	...	(L-4). Byte	(L-3). Byte	(L-2). Byte	(L-1). Byte	(L). Byte
Grafiksegment	Grafiksegment	...	Grafiksegment	Low Byte (Breite-1)	High Byte (Breite-1)	Low Byte (Höhe-1)	High Byte (Höhe-1)
hochauflösend: Pixel 0 = Bit 7 ... Pixel 7 = Bit 0				Breite-1		Höhe-1
multicolor: Pixel 0 = Bit 7+6 ... Pixel 3 = Bit 1+0

Die sich ergebende Zeichenkettenlänge (Byteanzahl) lässt sich nach folgenden Formeln berechnen:

• für den hochauflösenden Modus: (INT(ABS(X1-X2)/8)+1)*(ABS(Y1-Y2)+1)+4
• für den Mehrfarben-Modus: (INT(ABS(X1-X2)/4)+1)*(ABS(Y1-Y2)+1)+4

Beispiele

Animation

10 GRAPHIC 1,1
20 DIM C$(95)
30 FOR I=32 TO 127
40 CHAR 1,0,0,CHR$(I)
50 SSHAPE C$(I-32),0,0,7,7
60 NEXT
70 T$="DAS IST DIE PERFEKTE WELLE!"
80 GOSUB 1000
999 END
1000 FOR I=1 TO LEN(T$)
1010 GSHAPE C$(ASC(MID$(T$, I))-32),I*9,100+SIN(I*π/12)*24
1015 NEXT
1020 RETURN

Diese Beispiel kopiert die Zeichen mit den PETSCII-Codes von 32 bis 127 in ein String-Array, um damit anschließend den Text "DAS IST DIE PERFEKTE WELLE!" in Wellenform auf dem Grafikbildschirm auszugeben.

Shape-Daten anzeigen

100 GRAPHIC 1,1
110 DRAW 0,0 TO 7,7
120 B=FRE(1)
130 SSHAPE A$,0,0,0,250
140 GRAPHIC 0
200 PRINT "MEMORY-VERBRAUCH:" B-FRE(1)
210 PRINT "STRING-LAENGE:" LEN(A$)
220 A=POINTER(A$)
230 BANK 1
240 S=PEEK(A+1)+256*PEEK(A+2)
250 L=PEEK(A)
300 FOR I=S TO S+L-1
310 PRINT USING "#### #####  ##";I-S,HEX$(I),RIGHT$(HEX$(PEEK(I)),2)
320 NEXT

Liefert die textuelle Ausgabe (Auszug)

MEMORY-VERBRAUCH: 264 STRING-LAENGE: 255 0 FDFF 80 1 FE00 40 ... 251 FEFA 00 252 FEFB 00 253 FEFC FA 254 FEFD 00

In der linken oberen Ecke wird eine 8 Pixel lange schräge Linie gezeichnet, die von 0 abweichenden Inhalt bei den Shape-Daten bewirkt. Dann wird ein Shape in maximaler Y-Ausdehnung angelegt, wobei dann der Platzverbrauch des SSHAPE-Aufrufs ermittelt

1. im gesamten Variablenbereich,
2. die in der einer befindlichen Daten

angezeigt wird. Schließlich wird der String Byte für Byte ausgelesen und angezeigt.
Der 264 Byte Variablenverbrauch ergibt sich aus 7 Byte Variable + 255 Byte String + 2 Byte String-Heap Verwaltungsdaten.

Grafik als Sprite übernehmen

100 GRAPHIC 1,1
110 DRAW 1, 0,0 TO 23,20      (Links oben eine Art Fadenkreuz zeichnen)
120 DRAW 1, 0,20 TO 23,0
125 BOX 1, 0,0, 23,20
130 CIRCLE 1,12,10,10
140 SSHAPE A$, 0,0,23,20      (Einen 24×21 Bereich entspr. Sprite-Ausdehnung kopieren ...)
150 SPRSAV A$,1               (... und als Muster für Sprite #1 nehmen)
160 SPRITE 1,1,11,0,1,1,0     (Sprite #1 rot, in beiden Richtungen ausgedehnt darstellen)
170 MOVSPR 1,160,100          (Sprite in Bildschirmmitte)
180 MOVSPR 1,120#7            (Sprite nach rechts unten durchlaufen lassen)
190 GETKEY K$                 (auf Taste warten und ...)
200 GRAPHIC 0: MOVSPR 1,0#0   (Ende des Spuks)

Ein Beispiel für BASIC 7.0, bei dem eine grafische Form in ein Sprite übernommen wird.
Der Aufruf von SSHAPE in Zeile 140 kann auch auf diverse andere Arten erfolgen:

140 LOCATE 0,0                (Bezugspunkt für Verschiebungskoordinaten ...)
141 SSHAPE A$, +23,+20        (Einen 24×21 Bereich via relative Koordinaten)

oder

140 LOCATE 0,0                (Bezugspunkt für Vektorkoordinaten ...)
141 SSHAPE A$, 31.89;131.2    (Einen 24×21 Bereich via Diagonale, entspricht einer)
                              (Uhrzeigerposition bei ca. 22 Minuten, also etwa zwischen 4 h und 5 h)

Die relativen Angaben, sei es mit Länge+Winkel oder Verschiebungswerten, beziehen sich immer auf den Pixelcursor, der zuvor gesetzt wurde oder sich ergeben hat. Insbesondere ein absolutes Koordinatenpaar im gleichen Befehl als erstes Koordinatenangabe ändert den Pixelcursor nicht für die 2. Koordinatenangabe.

BASIC V3.5-Befehle der Commodore-264-Serie

AUTO | BACKUP | BOX | CHAR | CIRCLE | COLLECT | COLOR | COPY | DEC | DELETE | DIRECTORY | DLOAD | DO | DRAW | DS | DS$ | DSAVE | EL | ELSE | ER | ERR$ | EXIT | GETKEY | GRAPHIC | GSHAPE | HEADER | HELP | HEX$ | INSTR | JOY | KEY | LOCATE | LOOP | MONITOR | PAINT | PRINT USING | PUDEF | RCLR | RDOT | RENAME | RENUMBER | RESUME | RGR | RLUM | SCALE | SCNCLR | SCRATCH | SOUND | SSHAPE | TRAP | TROFF | TRON | UNTIL | VOL | WHILE