Eingaben aus Skripten referenzieren

Sowohl die Abbildungs-Skript- und Kurven-Skript -Komponenten ermöglichen es dir, benutzerdefinierte Eingaben wie Schieberegler, Checkbox usw. über das Dialogfeld Eingabe-Editor hinzuzufügen. Jeder Eingabetyp hat eine entsprechende Funktion, mit der du den Wert einer bestimmten Eingabe dieses Typs aus dem Skript abfragen kannst. Eingaben werden durch ihren Skript-Identifikator identifiziert, die im Eingabe-Editor angegeben werden. Abbildungsfähige Eingaben wie Farbkarte, Graustufe-Karte oder Kurve müssen mit der Funktion get_sample() des Skripts abgerufen werden, während numerische Eingaben wie Schieberegler und Checkbox mit der Funktion prepare() des Skripts abgefragt werden müssen. Diese Tabelle fasst die Informationen über die Eingabetypen und ihre entsprechenden Funktionen zusammen:

Farb-Abbildungs-Eingaben

Farb-Abbildungs-Eingaben werden durch den Aufruf der Funktion get_sample_map() mit den Koordinaten der Samples und dem Skript-Identifikator der Eingabe als Argumente gesampelt. Die Funktion gibt eine RGBA-Farbe zurück:

r, g, b, a = get_sample_map(x, y, input_id)

• r, g, b und a (Rückgabewerte) – RGBA-Kanäle der Farbe an den durch x und y angegebenen Sample-Koordinaten im Ausgabebild einer Komponente, die mit dem durch input_id angegebenen Eingang verbunden ist. Ist keine Abbildungs-Komponente mit dem Eingang verbunden, gibt die Funktion die Farbe des Farbfelds des Eingangs zurück.
  
  Für Eingaben, die im Eingabe-Editor nicht als "HDR-Eingabe" markiert sind, gibt get_sample_map() RGBA-Kanäle als Zahlen im Bereich 0…1 zurück. Bei HDR-Eingaben können die zurückgegebenen RGB-Werte (aber nicht der Alphakanalwert) außerhalb des Bereichs 0…1 liegen. Weitere Informationen darüber, wie Farben in Filter Forge dargestellt werden, findest du unter: HDR-Farben.
• x und y – Die Koordinaten des Sample-Punktes oder einfach Sample-Koordinaten. Ein Punkt mit den Koordinaten 0, 0 entspricht der linken oberen Ecke des Bildes, und ein Punkt mit den Koordinaten 1, 1 entspricht der rechten unteren Ecke des Quadrats Größe x Größe Pixel breit, wobei Größe der aktuelle Wert des globalen Schiebereglers Größe ist. Weitere Informationen über das Koordinatensystem von Filter Forge und das Sampling im Allgemeinen findest du unter: Die Sample-basierte Architektur von Filter Forge.
• input_id – Skript-Identifikator des gesampelten Farb-Abbildungs-Eingangs. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Farb-Abbildungs-Eingabe ist, wird das Skript mit einem Fehler beendet.

Der Aufruf von get_sample_map() muss aus der Funktion get_sample() des Skripts erfolgen. Wenn du sie von der Funktion prepare() des Skripts aus aufrufst, wird das Skript mit einem Fehler beendet.

Das folgende Beispielskript tastet zwei Farb-Abbildungs-Eingaben mit den Skript-Identifikator COLOR1 und COLOR2 ab und gibt ihre gemittelte Farbe zurück:

function prepare()
end;

function get_sample(x, y)
	r1,  g1, b1, a1 = get_sample_map(x, y, COLOR1)
	r2,  g2, b2, a2 = get_sample_map(x, y, COLOR2)
	return (r1+r2)/2, (g1+g2)/2, (b1+b2)/2, (a1+a2)/2
end;

Graustufen-Abbildungs-Eingaben

Graustufen-Abbildungs-Eingaben werden durch den Aufruf der Funktion get_sample_grayscale() mit den Koordinaten der Samples und dem Skript-Identifikator der Eingabe als Argumente gesampelt. Die Funktion gibt einen einzelnen numerischen Wert zurück:

v = get_sample_grayscale(x, y, input_id)

• v (Rückgabewerte) – Der Graustufenwert der Farbe an den durch x und y angegebenen Sample-Koordinaten im Ausgabebild einer Komponente, die mit dem durch input_id angegebenen Eingang verbunden ist. Ist keine Abbildungs-Komponente mit dem Eingang verbunden, gibt die Funktion den im numerischen Eingabefeld des Eingangs angegebenen Wert zurück. Der Graustufenwert wird durch Mittelwertbildung der RGB-Kanäle der Farbe an den Sample-Koordinaten und Multiplikation des Mittelwerts mit dem Alphakanal der Farbe berechnet:
  
  v = (R + G + B) / 3 * A
  
  Bei Eingaben, die im Eingabe-Editor nicht als "HDR-Eingabe" markiert sind, gibt get_sample_grayscale() den Wert als Zahl im Bereich 0…1 zurück. Bei HDR-Eingaben kann der zurückgegebene Wert außerhalb des Bereichs 0…1 liegen. Weitere Informationen findest du unter: HDR-Farben.
• x und y – Die Koordinaten des Samples-Punktes oder einfach Sample-Koordinaten. Ein Punkt mit den Koordinaten 0, 0 entspricht der linken oberen Ecke des Bildes, und ein Punkt mit den Koordinaten 1, 1 entspricht der rechten unteren Ecke des Quadrats Größe x Größe Pixel breit, wobei Größe der aktuelle Wert des globalen Schiebereglers Größe ist. Weitere Informationen über das Koordinatensystem von Filter Forge und das Sampling im Allgemeinen findest du unter: Die Sample-basierte Architektur von Filter Forge.
• input_id – Skript-Identifikator des abgetasteten Farb-Abbildungs-Eingangs. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Farb-Abbildungs-Eingabe ist, wird das Skript mit einem Fehler beendet.

Der Aufruf von get_sample_grayscale() muss aus der Funktion get_sample() des Skripts erfolgen. Wenn du sie von der Funktion prepare() des Skripts aus aufrufst, wird das Skript mit einem Fehler beendet.

Das folgende Beispielskript tastet zwei Graustufen-Abbildungs-Eingaben mit den Skript-Identifikator GRAY1 und GRAY2 ab und mischt die zurückgegebenen Graustufenwerte in die RGB-Kanäle der endgültigen Farbe:

function prepare()
end;

function get_sample(x, y)
	v1 = get_sample_grayscale(x, y, GRAY1)
	v2 = get_sample_grayscale(x, y, GRAY2)
	return v1, v2, (v1+v2)/2, 1
end;

Schieberegler-Eingaben

Schieberegler-Eingaben werden durch den Aufruf der Funktion get_slider_input() mit dem Skript-Identifikator des Eingangs als Argument abgefragt. Die Funktion gibt den aktuellen Wert des Schiebereglers als Zahl im Bereich von 0…1 zurück:

value = get_slider_input(input_id)

• value (Rückgabewert) – Der aktuelle Wert des durch input_id spezifizierten Schieberegler-Eingangs, der als Zahl im Bereich von 0…1 zurückgegeben wird – beachte, dass sich dieser tatsächliche Bereich von dem Anzeigebereich von 0…100 unterscheidet, der für die Anzeige von Werten von Schieberegler-Eingängen in der Benutzeroberfläche verwendet wird.
• input_id – Skript-Identifikator der abgefragten Schieberegler-Eingabe. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Schieberegler-Eingabe ist, bricht das Skript mit einem Fehler ab.

Diese Funktion muss von der prepare() des Skripts aufgerufen werden. Wenn du sie von der Funktion get_sample() aus aufrufst, wird das Skript mit einem Fehler abgebrochen. Wenn du den zurückgegebenen Wert in einer Variablen speicherst, stelle sicher, dass die Variable nicht als local deklariert ist, da du sonst von der Funktion get_sample() des Skripts nicht auf ihren Wert zugreifen kannst.

Das folgende Beispielskript erhält den Wert der Schieberegler-Eingabe mit dem Skript-Identifikator SLYDER aus der Funktions prepare() des Skripts, speichert das Ergebnis in einer Variablen namens v und verwendet die Variable in der Funktion get_sample() um eine flache Farbe mit der Helligkeit zurückzugeben, die dem Schiebereglerwert entspricht:

function prepare()
	v = get_slider_input(SLYDER)
end;

function get_sample(x, y)
	return v, v, v, 1
end;

Winkel-Eingaben

Winkel-Eingaben werden abgefragt, indem die Funktion get_angle_input() mit dem Skript-Identifikator der Eingabe als Argument aufgerufen wird. Die Funktion gibt den Wert der Eingabe als Zahl im Bereich von 0…360 zurück:

angle = get_angle_input(input_id)

• angle (Rückgabewert) – Der aktuelle Wert des durch input_id spezifizierten Winkel-Eingabe, zurückgegeben als Zahl im Bereich von 0…360.
• input_id – Skript-Identifikator der abgefragten Winkel-Eingabe. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Winkeleingabe ist, bricht das Skript mit einem Fehler ab.

Diese Funktion muss von prepare() des Skripts aufgerufen werden. Wenn du sie von der Funktion get_sample() aus aufrufst, wird das Skript mit einem Fehler abgebrochen. Wenn du den zurückgegebenen Wert in einer Variablen speicherst, stelle sicher, dass die Variable nicht als local deklariert ist, da du sonst von der Funktion get_sample() des Skripts nicht auf ihren Wert zugreifen kannst.

Das folgende Beispielskript erhält den Wert der Winkeleingabe mit dem Skript-Identifikator ANGIE aus der Funktion prepare() des Skripts, dividiert ihn durch 360, um ihn in den Bereich 0…1 zu bringen, speichert das Ergebnis in einer Variablen namens a und verwendet die Variable in der Funktion get_sample() um eine flache Farbe mit der durch den Wert der Winkeleingabe definierten Helligkeit zurückzugeben:

function prepare()
	a  = get_angle_input(ANGIE) / 360
end;

function get_sample(x, y)
	return a, a, a, 1
end;

Ganzzahl-Schieberegler-Eingaben

Ganzzahl Schieberegler-Eingaben werden durch Aufruf der Funktion get_intslider_input() mit dem Skript-Identifikator des Eingangs als Argument abgefragt. Die Funktion gibt den aktuellen Wert des Schiebereglers als Zahl zurück:

value = get_intslider_input(input_id)

• value (Rückgabewert #1) – Der aktuelle Wert des durch input_id angegebenen Ganzzahl-Schiebereglers, der als Zahl zurückgegeben wird, die dem Wert im numerischen Eingabefeld des Schiebereglers entspricht. Beachte, dass die aktuelle Version der Filter Forge-API keine Möglichkeit bietet, die für Ganzzahl-Schieberegler im Eingabe-Editor angegebenen Mindest- und Höchstwerte zu erhalten.
• input_id – Skript-Identifikator der abgefragten Ganzzahl-Schiebereglereingabe. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Ganzzahl-Schiebereglereingabe ist, bricht das Skript mit einem Fehler ab.

Diese Funktion muss von der Funktion prepare() des Skripts aufgerufen werden. Wenn du sie von der Funktion get_sample() aus aufrufst, wird das Skript mit einem Fehler abgebrochen. Wenn du den zurückgegebenen Wert in einer Variablen speicherst, stelle sicher, dass die Variable nicht als local deklariert ist, da du sonst von der Funktion get_sample() des Skripts nicht auf ihren Wert zugreifen kannst.

Das folgende Beispielskript erhält den Wert des Ganzzahl-Schiebereglers mit dem Skript-Identifikator STEPS aus der Funktion prepare() des Skripts, speichert das Ergebnis in einer Variablen namens steps und verwendet die Variable in der Funktion get_sample(), um einen linearen Farbverlauf mit flachen Stufen zu erzeugen:

function prepare()
	steps = get_intslider_input(STEPS)
end;

function get_sample(x, y)
	level = 1 / ( steps + 1  )
	v = math.floor( x /  level ) * level
	return v, v, v, 1
end;

Checkbox-Eingaben

Checkbox-Eingaben werden abgefragt, indem die Funktion get_checkbox_input() mit dem Skript-Identifikator der Eingabe als Argument aufgerufen wird. Die Funktion gibt true oder false zurück, je nach Status der Checkbox.

state = get_checkbox_input(input_id)

• state (Rückgabewert) – Der Status des durch input_id angegebenen Ankreuzfeldes. Wenn die Checkbox markiert ist, wird state als true zurückgegeben, und wenn die Checkbox nicht markiert ist, wird false zurückgegeben.
• input_id – Skript-Identifikator der abgefragten Checkbox. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Checkbox-Eingabe ist, bricht das Skript mit einem Fehler ab.

Diese Funktion muss von der Funktion prepare() des Skripts aufgerufen werden. Wenn du sie von der Funktion get_sample() aus aufrufst, wird das Skript mit einem Fehler abgebrochen. Wenn du den zurückgegebenen Wert in einer Variablen speicherst, stelle sicher, dass die Variable nicht als local deklariert ist, da du sonst von der Funktion get_sample() des Skripts nicht auf ihren Wert zugreifen kannst.

Das folgende Beispielskript fragt den Status einer Checkbox mit dem Skript-Identifikator TICK in der Funktion prepare() des Skripts ab, speichert das Ergebnis in einer Variablen namens chk und liest den Wert der Variablen mit der Funktion get_sample():

function prepare()
	chk = get_checkbox_input(TICK)
end;

function get_sample(x, y)
	if chk then
		return  1, 1, 1, 1
	else
    	return  0, 0, 0, 1
	end;
end;

Kurven-Eingaben

Kurven-Eingaben werden durch den Aufruf der Funktion get_sample_curve() mit den Sample-Koordinaten, dem Wert des Kurvenarguments und dem Skript-Identifikator der Eingabe als Argumente abgetastet:

c = get_sample_curve(x, y, t, input_id)

• c (Rückgabewert) – Der Ausgabewert der Funktion, die durch die Kurvenkomponente dargestellt wird, die mit dem durch input_id angegebenen Eingang für den angegebenen Kurvenargumentwert t verbunden ist. Wenn keine Kurven-Komponente an den Eingang angeschlossen ist, wird eine lineare Funktion abgetastet. Der Wert wird als Zahl im Bereich 0…1 zurückgegeben (aufgrund der Tatsache, dass Kurven-Komponenten keine HDR-Werte ausgeben können).
• x und y – Die Koordinaten des Sample-Punktes, oder einfach Sample-Koordinaten. Die Verwendung von Sample-Koordinaten für das Sampling einer Kurve mag seltsam erscheinen, aber diese Koordinaten sind notwendig, weil die Kurven-Komponenten von Filter Forge Abbildungs-Eingaben haben können und die von ihnen erzeugte Kurve daher an verschiedenen Sample-Punkten eine andere Form haben kann. Weitere Informationen darüber, wie das Abbilden für Kurven funktioniert, findest du unter: Abbildungs-Eingaben.
  
  Ein Punkt mit den Koordinaten 0, 0 entspricht der linken oberen Ecke des Bildes, und ein Punkt mit den Koordinaten 1, 1 entspricht der rechten unteren Ecke des Quadrats Größe x Größe Pixel breit, wobei Größe der aktuelle Wert des globalen Schiebereglers Größe ist. Weitere Informationen über das Koordinatensystem von Filter Forge und das Sampling im Allgemeinen findest du unter: Die Sample-basierte Architektur von Filter Forge.
• t – Der Wert des Kurvenarguments. In den meisten Fällen wird dies eine Zahl innerhalb des Bereichs 0…1 sein, kann aber auch über diesen Bereich hinausgehen – Die Kurven-Komponenten von Filter Forge müssen in der Lage sein, Argumente jenseits des Bereichs 0…1 zu verarbeiten.
• input_id – Skript-Identifikator des abgetasteten Farb-Abbildungs-Eingangs. Wenn es im Eingabe-Editor keine Eingabe mit diesem Skript-Identifikator gibt oder die Eingabe mit dem passenden Skript-Identifikator keine Kurvenabbildungs-Eingabe ist, bricht das Skript mit einem Fehler ab.

Der Aufruf von get_sample_curve() muss über die Funktion get_sample() des Skripts erfolgen. Wenn du sie von der Funktion prepare() aus aufrufst, bricht das Skript mit einem Fehler ab.

Das folgende Beispielskript tastet eine Kurven-Eingabe mit dem Skript-Identifikator PROFILE ab und erzeugt einen neu zugeordneten radialen Farbverlauf. Vergiss nicht, eine Kurven-Komponente mit dem Eingang zu verbinden, wenn du dieses Beispiel ausführst:

function prepare()
end;

function get_sample(x, y)
	distance = math.sqrt  (x*x + y*y)

	c  = get_sample_curve(x, y, distance, PROFILE)
	return c, c, c, 1
end;