From ce5cf520b3bc17016aafa4ed33809a04c28e40c5 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Mon, 25 Jan 2010 20:35:36 -0800
Subject: [PATCH] docs for audio.vorbis

---
 extra/audio/vorbis/authors.txt        |  2 ++
 extra/audio/vorbis/summary.txt        |  1 +
 extra/audio/vorbis/vorbis-docs.factor | 48 +++++++++++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 extra/audio/vorbis/authors.txt
 create mode 100644 extra/audio/vorbis/summary.txt
 create mode 100644 extra/audio/vorbis/vorbis-docs.factor

diff --git a/extra/audio/vorbis/authors.txt b/extra/audio/vorbis/authors.txt
new file mode 100644
index 0000000000..338647c8b8
--- /dev/null
+++ b/extra/audio/vorbis/authors.txt
@@ -0,0 +1,2 @@
+Chris Double
+Joe Groff
diff --git a/extra/audio/vorbis/summary.txt b/extra/audio/vorbis/summary.txt
new file mode 100644
index 0000000000..9ca85046ef
--- /dev/null
+++ b/extra/audio/vorbis/summary.txt
@@ -0,0 +1 @@
+Ogg Vorbis audio streaming for audio.engine
diff --git a/extra/audio/vorbis/vorbis-docs.factor b/extra/audio/vorbis/vorbis-docs.factor
new file mode 100644
index 0000000000..379e8834f9
--- /dev/null
+++ b/extra/audio/vorbis/vorbis-docs.factor
@@ -0,0 +1,48 @@
+! (c)2010 Joe Groff bsd license
+USING: audio.engine destructors help.markup help.syntax
+io.files kernel math strings ;
+IN: audio.vorbis
+
+HELP: <vorbis-stream>
+{ $values
+    { "stream" "a binary input stream" } { "buffer-size" integer }
+    { "vorbis-stream" vorbis-stream }
+}
+{ $description "Constructs " { $link vorbis-stream } " over the contents of " { $snippet "stream" } ". When used as an audio generator, the Vorbis stream will supply data to the audio engine in " { $snippet "buffer-size" } " byte blocks. If the Vorbis stream is created successfully, it will take ownership of " { $snippet "stream" } ", disposing it when " { $link dispose } " is called on the " { $snippet "vorbis-stream" } "." } ;
+
+HELP: no-vorbis-in-ogg
+{ $description { $link <vorbis-stream> } " throws this error when the Ogg stream it reads contains no Vorbis channel." } ;
+
+HELP: ogg-error
+{ $values
+    { "code" integer }
+}
+{ $description { $link <vorbis-stream> } " throws this error when the Ogg library raises an error while trying to parse the stream." } ;
+
+HELP: read-vorbis-stream
+{ $values
+    { "filename" string } { "buffer-size" integer }
+    { "vorbis-stream" vorbis-stream }
+}
+{ $description "Opens a binary " { $link <file-reader> } " for the file named " { $snippet "filename" } ", and construct a " { $link vorbis-stream } " over the file contents using " { $link <vorbis-stream> } "." } ;
+
+{ read-vorbis-stream <vorbis-stream> } related-words
+
+HELP: vorbis-error
+{ $values
+    { "code" integer }
+}
+{ $description { $link <vorbis-stream> } " throws this error when the Vorbis library raises an error while trying to parse the stream." } ;
+
+HELP: vorbis-stream
+{ $class-description "Objects of this class maintain the stream and decoder state for the Ogg Vorbis decoder. " { $snippet "vorbis-stream" } " implements the " { $link "audio.engine-generators" } ", so it can be used as the generator for a " { $link streaming-audio-clip } ". Use " { $link <vorbis-stream> } " or " { $link read-vorbis-stream } " to construct a Vorbis stream." } ;
+
+ARTICLE: "audio.vorbis" "Ogg Vorbis audio streaming"
+"The " { $vocab-link "audio.vorbis" } " vocabulary provides Ogg Vorbis decoding and streaming for " { $vocab-link "audio.engine" } "."
+{ $subsections
+    vorbis-stream
+    read-vorbis-stream
+    <vorbis-stream>
+} ;
+
+ABOUT: "audio.vorbis"