| Aktuelle Version |
Dein Text |
| Zeile 121: |
Zeile 121: |
| | | | |
| | === Blocking === | | === Blocking === |
| − | Die normale Betriebsart für das Schreiben und Lesen von Streams ist ''Blocking''. Das heißt, dass wenn man zu schnell schreibt oder liest der Schreib- oder Lesebefehl ''blockiert'' bis wieder genug Puffer oder Daten verfügbar ist. Dies dient dazu eine einfache Flusskontrolle zu haben. Für viele einfache Applikationen ist dies ausreichend. Mansche Applikationen benötigen es aber dass sie nicht an solchen Operationen Zwangs-Pausiert werden. Um dies zu unterbinden kann man in den so genannten ''Non-Blocking'' Modus gehen. In diesem Fall kehren die Ein-/Ausgabefunktionen unmittelbar zurück, auch wenn kein Puffer oder keine Daten verfügbar sind.
| + | ... |
| − | | |
| − | Die Funktion ''roar_vs_blocking()'' Kann verwendet werden um den Modus zu setzen. Die Funktion erwartet, neben Verbindungs-Objekt und Fehlercode Pointer, einen Wahrheitswert der den neuen Zustand angibt. Dieser kann entweder ROAR_VS_TRUE, ROAR_VS_FALSE, ROAR_VS_TOGGLE oder ROAR_VS_ASK sein.
| |
| − | | |
| − | Als Rückgabewert erhält man den alten Modus (ROAR_VS_TRUE für Blockend, ROAR_VS_FALSE für nicht blockend) oder -1 im Fehlerfall zurück.
| |
| − | | |
| − | ==== Beispiel ====
| |
| − | int old;
| |
| − |
| |
| − | old = roar_vs_blocking(vss, ROAR_VS_FALSE, &err);
| |
| | | | |
| | === Position und Latenz === | | === Position und Latenz === |
| Zeile 168: |
Zeile 159: |
| | | | |
| | === Lautstärke === | | === Lautstärke === |
| − | Die Lautstärke des Streams kann sowohl gelesen als auch gesetzt werden. Hier soll beides Behandelt werden.
| + | ... |
| − | | |
| − | die VS API verwendet native floats zur darstellung der Lautstärke. Der Wertebereich ist 0 (Signal wird komplett ausgeblendet. Sollte jedoch nicht verwendet werden um eine Mute Funktion zu implementieren) bis 1 (Volle Signalstärke).
| |
| − | | |
| − | Gesetzt werden kann die Lautstärke entweder als Einkanal Wert oder als Stereo Wert. Die Funktion ''roar_vs_volume_mono()'' kann verwendet werden um sie als Einkanal Wert zu setzen. Diese Funktion erwartet neben dem Verbindungs-Objekt und dem Fehlerocode Pointer nur noch die neue Lautstärke.
| |
| − | | |
| − | Die Funktion ''roar_vs_volume_stereo()'' kann dazu verwendet werden den Wert als Stereo Wert zu setzen. Sie verwendet zwei Lautstärke Parameter. Einen für den linken und einen für den rechten Kanal.
| |
| − | | |
| − | Zum lesen kommt die Funktion ''roar_vs_volume_get()'' zum Einsatz. Diese erwartet, neben Verbindungs-Objekt und Fehlerocode Pointer, zwei Pointer, einen für den linken und einen für den rechten Kanal.
| |
| − | | |
| − | Möchte man nur eine Einkanal Information über die Lautstärke erfahren so kann man folgende Formel benutzen:
| |
| − | <math>c = \frac{l + r}{2}</math>
| |
| − | | |
| − | ==== Beispiele ====
| |
| − | float c, l, r;
| |
| − | int ret;
| |
| − |
| |
| − | c = 0.5;
| |
| − | ret = roar_vs_volume_mono(vss, c, &err);
| |
| − |
| |
| − | l = 0.8;
| |
| − | r = 0.2;
| |
| − | ret = roar_vs_volume_stereo(vss, l, r, &err);
| |
| − |
| |
| − | ret = roar_vs_volume_get(vss, &l, &r, &err);
| |
| − | c = (l + r)/2;
| |
| | | | |
| | === Meta Daten === | | === Meta Daten === |
| Zeile 256: |
Zeile 222: |
| | | | |
| | == Interaktion mit der Haupt API == | | == Interaktion mit der Haupt API == |
| − | Dieser Teil soll nur die Grundlagen der Interaktion mit der Haupt API erläutern. Die Verwendung dieser soll hier nicht beschreiben werden da dies viel zu umfangreich für dieses Dokument währe.
| + | ... |
| − | | |
| − | === Zugriff auf das Connection-, das Stream- und das VIO-Objekt ===
| |
| − | Wie auch unter Verwendung der Haupt API befindet sich im inneren des VS Verbindungs-Objekts eine Connection-, ein Stream- und ein VIO-Objekt. Auf diese kann man wie im folgenden Beispiel gezeigt mittels der Funktionen ''roar_vs_connection_obj()'', ''roar_vs_stream_obj()'' und ''roar_vs_vio_obj()'' zugreifen.
| |
| − | | |
| − | ==== Beispiele ====
| |
| − | struct roar_connection * con;
| |
| − | struct roar_stream * stream;
| |
| − | struct roar_vio_calls * vio;
| |
| − |
| |
| − | con = roar_vs_connection_obj(vss, &err);
| |
| − | stream = roar_vs_stream_obj(vss, &err);
| |
| − | vio = roar_vs_vio_obj(vss, &err);
| |
| − | | |
| − | === Verwenden einer bereits offenen Verbindung zu einem Server ===
| |
| − | Sollte bereits eine Verbindung bestehen kann das vorhandene Connection-Objekt verwendet werden um VS Verbindungs-Objekte davon zu erzeugen. Wichtig hierbei ist das bei trennen der Verbindung zu erst alle VS Verbindungs-Objekte getrennt werden müssen und danach erst das Connection-Objekt.
| |
| − | | |
| − | Das Vorgehen ein Connection-Objekt kann als Beispiel dann sinnvoll sein, sollten vielen VS Verbindungs-Objekte benötigt werden um das ständige Neu verbinden zu unterdrücken. Dies reduziert auch deutlich die möglichen Fehler.
| |
| − | | |
| − | Zur Verwendung einer externen Verbindung wird die Funktion ''roar_vs_new_from_con()'' verwendet. Diese benötigt als Parameter lediglich das Connection-Objekt und den Fehlercode pointer.
| |
| − | | |
| − | Es wird das neue Verbindungs-Objekt oder NULL zurück gegeben.
| |
| − | | |
| − | Ein Stream muss anschließend wie im folgenden gezeigt mittels ''roar_vs_stream()'' erzeugt werden.
| |
| − | | |
| − | ==== Beispiel ====
| |
| − | roar_vs_t * vss;
| |
| − |
| |
| − | vss = roar_vs_new_from_con(con, &err);
| |
| − | | |
| − | === Verwendung von VS Verbindungs-Objekts mit nachträglicher Stream Erzeugung ===
| |
| − | Ein VS Verbindungs-Objekt muss nicht von Anfang an mit einem Stream verbunden sein. Dies kann als Beispiel dann interessant sein sollte man mittels Haupt API weitere Parameter mit dem Server ab prüfen wollen bevor man den Stream erzeugt. Auch kann man so einen zweiten Versuch starten einen Stream zu öffnen (mit anderen Parametern) sollte der Server den Stream mit den gewünschten Parametern nicht annehmen ohne neu Verbinden zu müssen.
| |
| − | | |
| − | Zu erst muss dazu ein Nicht mit einem Stream verbundenes Verbinungs-Objekt erzeugt werden. Dies kann entweder mittels der oben beschriebenen Funktion ''roar_vs_new_from_con()'' oder mittels der Funktion ''roar_vs_new()'' geschehen.
| |
| − | | |
| − | Im Gegensatz zu ''roar_vs_new_from_con()'' erzeugt ''roar_vs_new()'' selbstständig eine Verbindung zum Server. ''roar_vs_new()'' erwartet um dies zu tun drei Parameter: Die Adresse des Servers (oder NULL um Defaults zu verwenden), den Namen unseres Klienten und den Fehlercode Pointer. Siehe hierzu auch das Beispiel am ende dieses Teils.
| |
| − | | |
| − | Um nun einen Stream zu erzeugen und zu Verbinden wird die Funktion ''roar_vs_stream()'' verwendet. Diese benötigt, neben dem Verbindungs-Objekt und dem Fehlercode Pointer, das Audio-Informations Struct und die Angabe der Stream Direction. Sollte diese Funktion Fehlschlagen ist es möglich erneut zu versuchen einen Stream (mit anderen Parametern) zu verbinden. Ausgenommen hiervon ist der Fall, dass das Objekt bereits verbunden ist da in diesem Fall es nicht sinnvoll ist diese Funktion auf zu rufen.
| |
| − | | |
| − | ==== Beispiele ====
| |
| − | roar_vs_t * vss;
| |
| − | struct roar_audio_info info;
| |
| − | int ret;
| |
| − |
| |
| − | info.bits = 16;
| |
| − | info.rate = 44100;
| |
| − | info.channels = 2;
| |
| − | info.codec = ROAR_CODEC_DEFAULT;
| |
| − |
| |
| − | vss = roar_vs_new(NULL, "MyApp", &err);
| |
| − |
| |
| − | // Fehler hier Behandeln.
| |
| − |
| |
| − | ret = roar_vs_stream(vss, &info, ROAR_DIR_PLAY, &err);
| |
| | | | |
| | == Siehe Auch == | | == Siehe Auch == |
