### Overlay

`Overlay(`clip clip, clip overlay [,int x, int y, clip mask, float opacity, string mode, bool greymask, string output, bool ignore_conditional, bool pc_range]`)`
`Overlay` legt zwei Clips übereinander, wobei man das überlagernde Bild positionieren kann und zwischen verschiedenen Methoden, wie überlagert werden soll, wählen kann. Weiterhin kann man die Transparenz des überlagernden Clips einstellen.
`Overlay` akzeptiert als Quelle alle Farbformate. Die Quellclips werden intern in ein allgemeines YUV Format (ohne Subsampling) konvertiert, so dass der Filter auch ein anderes Farbformat ausgeben kann als das Quell-Farbformat. Es ist auch nicht notwendig, dass die beiden Quellclips im gleichen Farbformat sind, da sie eh erstmal intern konvertiert werden. Es wird aber nicht empfohlen, `Overlay` nur für einen Wechsel des Farbformates zu verwenden, da es langsamer und von etwas schlechterer Qualität ist als die Standard-Konvertierungen.
Im Allgemeinen werden alle Clips mit Werten zwischen 0 bis 255 verarbeitet. Soll heißen, die Werte werden nicht auf den CCIR 601 Bereich beschnitten. Dazu kann man im Nachhinein Limiter nutzen. Die Masken sollte auch Werte von 0 bis 255 haben. Man kann Histogram mit `Histogram("levels")` nutzen, um sich die Farbverteilung anzusehen. Falls die Maske im CCIR 601 Bereich ist, verwende vorher ColorYUV mit `ColorYUV(levels="TV->PC")`, um die Farbwerte hochzurechnen.
Es wird nicht empfohlen, interlaced Material zu überlagern, es sei denn, man weiß wirklich, was man da tut.

Parameter:
clip | Dies ist der grundlegende Clip, auf den man dann etwas überlagern kann.
overlay | Dies ist der Clip, der überlagert wird. Der Farbraum und/oder die Auflösung muss nicht mit der vom darunterliegenden Clip übereinstimmen.
x | Bestimmt die Position des überlagerten Clips in horizontaler Richtung in Pixel. Der Parameter kann positive und negative Werte annehmen. Standard ist 0.
y | Bestimmt die Position des überlagerten Clips in vertikaler Richtung in Pixel. Der Parameter kann positive und negative Werte annehmen. Standard ist 0.
mask | Hier kann man einen Clip angeben, der als Transparenz-Maske für den überlagerten Clip fungiert. Die Maske muss die selbe Auflösung haben wie der überlagerte Clip. Selbstverständlich wird nur die Helligkeit (Luma) vom Clip für die Maske verwendet. Um so dunkler der Maske ist, um so transparenter wird der überlagerte Clip. Es gibt keinen Standard, aber wenn man nichts weiter angibt, so ist gleichbedeutend mit einem 255 (weiß) Clip.
opacity | Dies definiert, wie transparent der überlagerte Clip allgemein sein soll. Der Wert geht von 0.0 bis 1.0, wobei 0.0 komplett transparent ist und 1.0 völlig undurchlässig ist (falls es keinen mask Clip gibt). Wenn man eine Maske verwendet, wird dieser Wert mit dem Masken-Wert multipliziert für die endgültige Transparenz. Standard ist 1.0.
mode | Mit diesem Parameter (in Anführungszeichen!) kann man bestimmen, wie die Clips überlagert werden (Standard ist Blend):
Blend | Wenn opacity=1.0 ist und es keine Maske gibt, dann wird der überlagernde Clip einfach über den grundlegenden Clip gelegt. Ansonsten wird der Clip transparent miteingeblendet.
Add | Dies addiert den überlagernden Clip zu dem anderen Clip, was das Video heller macht. Um dies vergleichbar zu RGB zu machen, beeinflussen übermäßig helle Flächen die Farben, indem sie weißer werden.
Subtract | Das Gegenteil von Add. Dies macht Flächen dunkler.
Multiply | Dies macht das Bild auch dunkler, aber es funktioniert anders als Subtract.
Chroma | Es werden nur die Farbinformationen des überlagernden Clips genutzt.
Luma | Es werden nur die Helligkeitsinformationen des überlagernden Clips genutzt.
Lighten | Es werden nur die hellen Informationen des überlagernden Clips kopiert, aber nur wenn sie heller sind als die Werte des grundlegenden Clips.
Darken | Es werden nur die hellen Informationen des überlagernden Clips kopiert, aber nur wenn sie dunkler sind als die Werte des grundlegenden Clips
SoftLight | Dies macht den grundlegenden Clip heller oder dunkler, basierend auf der Helligkeit des überlagernden Clips. Falls dieser dunkler als luma=128 ist, wird das grundlegende Bild dunkler; falls dieser heller als luma=128 ist, wird das grundlegende Bild heller. Dies ist sinnvoll, wenn man Schatten hinzufügen will. Komplett schwarz oder weiß resultiert in deutlich dunkleren beziehungsweise helleren Flächen, aber niemals komplett schwarz oder weiß.
Hardlight | Dies macht den grundlegenden Clip heller oder dunkler, basierend auf der Helligkeit des überlagernden Clips. Falls dieser dunkler als luma=128 ist, wird das grundlegende Bild dunkler; falls dieser heller als luma=128 ist, wird das grundlegende Bild heller. Dies ist sinnvoll, wenn man Schatten hinzufügen will. Komplett schwarz oder weiß resultiert in komplett schwarz beziehungsweise weiß.
Difference | Dies zeigt die Unterschiede zwischen den beiden Clips an. Beachte, dass die Unterschiede wie bei Subtract mit grau=127 angezeigt werden. Wenn du die reinen Unterschiede willst, verwende `ColorYUV(off_y=-127)`.
Exclusion | Es wird der grundlegende Clip invertiert basierend auf der Helligkeit des überlagernden Clips. Ist dieser komplett weiß, so werden die Farben vollständig invertiert; ist dieser schwarz, so passiert gar nichts.
greymask | Mit diesem Parameter kann man angeben, ob die Farbe der Maske für die Farbtransparenz genutzt werden soll. Allgemein sollte man diese Option nicht deaktivieren. Externe Plugins wie mSharpen oder Masktools sind in der Lage, exakte Farbkarten zu erstellen. Standard ist true.
output | Hiermit kann man das Farbformat des resultierenden Clips ändern. Mögliche Werte sind "YV12", "YUY2", "RGB24" und "RGB32" (in Anführungsstrichen!). Standard ist das Farbformat der Quelle.
ignore_conditional | Hiermit kann man `Overlay` dazu bringen, die bedingten Variablen zu ignorieren. Standard ist false. Dies ist nützlich, wenn man `Overlay` mehrfach anwendet. Conditional Variables: Die globalen Variablen OL_opacity_offset, OL_x_offset und OL_y_offset werden bei jeden Frame abgefragt und angewendet. Man kann sie über FrameEvaluate modifizieren. Die Werte der Variablen werden zu den Werten des Filters addiert, so dass, wenn z.B. x=100 bei Filter und ol_x_offset=50 als globale Variable definiert ist, der von `Overlay` genutzte Wert für x=150 ist.
pc_range | Bei true wird bei allen internen RGB -> YUV -> RGB Farbraumkonvertierung von einem Helligkeitsbereich von 0 bis 255 ausgegangen anstatt des standardmäßen Bereiches von 16 -> 235. Man sollte diesen Parameter nur ändern, wenn man weiß, was man da tut. Siehe auch den Hinweis "RGB Hinweise" unten. Standard ist false

RGB Hinweise:
Die Sektion beschreibt Sachen, warum `Overlay` funktioniert, wenn man ihm eine oder mehrere RGB Quellen liefert.
Eine oder mehrere RGB Quellen sind bei `Overlay` erlaubt. Da aber `Overlay` die Daten intern im YUV Farbraum verarbeitet, wird dann eine RGB -> YUV Konvertierung gemacht. Es gibt dabei zwei Modi, die man mit dem pc_range Parameter einstellt. Dieser Parameter erweitert den YUV Bereich von 16-235 (wird von alle AviSynth Konvertern genutzt) auf 0-255. Es gibt aber einige Fälle, wo es eine gute Idee ist, den erweiterten PC Bereich zu wählen:

- Wenn einen RGB Clip überlagert mit Add, Subtract oder Multiply, der PC Bereich (0-255) ist für den überlagernden Clip besser, da so komplett schwarze Flächen nicht beeinflusst werden (ansonsten werden 16 zu jedem Wert hinzuaddiert).
- Wenn man bei der Ausgabe KEINE Farbraumkonvertierung hat. Falls der Ziel-Farbraum (RGB vs. YUV) unterschiedlich von der Quelle ist, ist die Skalierung falsch. Bei pc_range=true und einer RGB Quelle und YUY2 als Zielformat, wird YUY2 eine ungültigen Bereich haben anstatt dem CCIR 601 Bereich.

Ausgabe von RGB:
Es kann eine gute Idee sein, dass `Overlay` als Zielformat YUY2 liefert, auch wenn die Quelle RGB ist, da dies eine Farbraumkonvertierung zu RGB erspart. Man sollte aber darauf achten, dass die Daten nicht "überskaliert" sind, wie oben erwähnt, wenn man pc_range=true setzt. Dies kann man dann mit `ColorYUV(levels="PC->TV")` auf den gültigen 16-235 Bereich korrigieren.
RGB Masken Clips:
RGB Masken können sich etwas anders verhalten, als man denkt. Falls du immer eine grauskalierte Maske verwendest und greymask nicht deaktivierst, wirst du alles wie erwartet funktionieren. Man sollte wissen, dass die Masken nie auf den 16->235 Bereich skaliert werden, so dass man bei RGB immer den 0->255 Bereich hat.
Verwendung des RGB32 Alpha Kanales:
`Overlay` verwendet nie den Alpha Kanal eines RGB32 Clips. Wenn du diesen Alpha Kanal haben willst, kannst du ShowAlpha verwenden, um die Alpha Informationen zu extrahieren. Für höchstmögliche Qualität sollte man den Alpha Kanal in RGB extrahieren.

Beispiele:
`bg = ColorBars(512,384).ConvertToYUY2() text = BlankClip(bg).Subtitle("Colorbars").ColorYUV(levels="TV->PC")` | Bereitet einige Quelle vor
`Overlay(bg,text,x=50,y=20,mode="subtract",opacity=0.25) Overlay(text,x=50,y=120,mode="add",opacity=0.5) Overlay(text,x=50,y=240,mode="blend",opacity=0.7)` | Diese überlagert den Text in drei unterschiedlichen Versionen

Changelog:
`v2.54` | Erstes Release