ref: 9926a466c5d97ba38d815502c4442f01d5170ab8
parent: 1f2f0bc451eb1e915797ee9b753062f3325b1858
author: Timothy B. Terriberry <tterribe@xiph.org>
date: Sun Sep 30 19:23:05 EDT 2012
Documentation updates. * Add Opus logo. * Use @VERSION@ consistently. * Fix some warnings/formatting exposed by a newer Doxygen versions.
--- a/Makefile.am
+++ b/Makefile.am
@@ -27,11 +27,12 @@
if HAVE_DOXYGEN
-EXTRA_DIST = doc/Doxyfile.in doc/git-version.sh
+EXTRA_DIST = doc/Doxyfile.in doc/opus_logo.svg
all-local: doc/doxygen-build.stamp
-doc/doxygen-build.stamp: doc/Doxyfile $(top_srcdir)/include/*.h
+doc/doxygen-build.stamp: doc/Doxyfile $(top_srcdir)/doc/opus_logo.svg \
+ $(top_srcdir)/include/*.h
cd doc && doxygen
touch "$@"
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -6,7 +6,7 @@
INPUT = @top_srcdir@/include/opusfile.h
OPTIMIZE_OUTPUT_FOR_C = YES
-FILE_VERSION_FILTER = "/bin/sh @top_srcdir@/doc/git-version.sh"
+FILE_VERSION_FILTER = "echo @VERSION@"
QUIET = YES
WARNINGS = YES
@@ -16,3 +16,5 @@
JAVADOC_AUTOBRIEF = YES
SORT_MEMBER_DOCS = NO
+
+PROJECT_LOGO = @top_srcdir@/doc/opus_logo.svg
--- /dev/null
+++ b/doc/opus_logo.svg
@@ -1,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="1.1"
+ x="0px"
+ y="0px"
+ width="97"
+ height="55"
+ viewBox="-72 -23.757 97 55"
+ overflow="visible"
+ enable-background="new -72 -23.757 169 78.757"
+ xml:space="preserve"
+ id="svg2"
+ style="overflow:visible">
+<defs
+ id="defs4">
+<linearGradient
+ xlink:href="#SVGID_1_"
+ id="linearGradient3027"
+ gradientUnits="userSpaceOnUse"
+ x1="194.53169"
+ y1="95.107399"
+ x2="194.53169"
+ y2="9.9475983e-14" /><linearGradient
+ xlink:href="#SVGID_2_"
+ id="linearGradient3029"
+ gradientUnits="userSpaceOnUse"
+ x1="229.61819"
+ y1="116.208"
+ x2="229.61819"
+ y2="164.46291" /><linearGradient
+ xlink:href="#SVGID_3_"
+ id="linearGradient3031"
+ gradientUnits="userSpaceOnUse"
+ x1="43.9897"
+ y1="115.4395"
+ x2="43.9897"
+ y2="165.2314" /><linearGradient
+ xlink:href="#SVGID_4_"
+ id="linearGradient3033"
+ gradientUnits="userSpaceOnUse"
+ x1="311.2847"
+ y1="115.7188"
+ x2="311.2847"
+ y2="165.2822" /><linearGradient
+ xlink:href="#SVGID_5_"
+ id="linearGradient3035"
+ gradientUnits="userSpaceOnUse"
+ x1="129.1987"
+ y1="115.5791"
+ x2="129.1987"
+ y2="204.4863" /></defs>
+<linearGradient
+ id="SVGID_1_"
+ gradientUnits="userSpaceOnUse"
+ x1="194.53169"
+ y1="95.107399"
+ x2="194.53169"
+ y2="9.9475983e-14">
+ <stop
+ offset="0.0056"
+ style="stop-color:#8E8E8E"
+ id="stop7" />
+ <stop
+ offset="1"
+ style="stop-color:#B5B5B5"
+ id="stop9" />
+</linearGradient>
+
+<linearGradient
+ id="SVGID_2_"
+ gradientUnits="userSpaceOnUse"
+ x1="229.61819"
+ y1="116.208"
+ x2="229.61819"
+ y2="164.46291">
+ <stop
+ offset="0.0056"
+ style="stop-color:#494748"
+ id="stop14" />
+ <stop
+ offset="1"
+ style="stop-color:#000000"
+ id="stop16" />
+</linearGradient>
+
+<linearGradient
+ id="SVGID_3_"
+ gradientUnits="userSpaceOnUse"
+ x1="43.9897"
+ y1="115.4395"
+ x2="43.9897"
+ y2="165.2314">
+ <stop
+ offset="0.0056"
+ style="stop-color:#494748"
+ id="stop21" />
+ <stop
+ offset="1"
+ style="stop-color:#000000"
+ id="stop23" />
+</linearGradient>
+
+<linearGradient
+ id="SVGID_4_"
+ gradientUnits="userSpaceOnUse"
+ x1="311.2847"
+ y1="115.7188"
+ x2="311.2847"
+ y2="165.2822">
+ <stop
+ offset="0.0056"
+ style="stop-color:#494748"
+ id="stop28" />
+ <stop
+ offset="1"
+ style="stop-color:#000000"
+ id="stop30" />
+</linearGradient>
+
+<linearGradient
+ id="SVGID_5_"
+ gradientUnits="userSpaceOnUse"
+ x1="129.1987"
+ y1="115.5791"
+ x2="129.1987"
+ y2="204.4863">
+ <stop
+ offset="0.0056"
+ style="stop-color:#494748"
+ id="stop35" />
+ <stop
+ offset="1"
+ style="stop-color:#000000"
+ id="stop37" />
+</linearGradient>
+<g
+ id="g3020"
+ transform="matrix(0.26931937,0,0,0.26931937,-72.00048,-23.756955)"><path
+ id="path11"
+ d="M 257.355,13.996 C 249.943,7.826 238.533,3.695 223.153,1.588 l -11.302,35.935 c -0.244,1.318 -0.664,2.815 -1.315,4.54 -1.153,2.883 -2.542,5.258 -4.174,7.127 -1.634,1.874 -3.463,3.335 -5.489,4.4 -2.028,1.059 -4.232,1.79 -6.614,2.193 -2.382,0.4 -4.847,0.526 -7.393,0.378 -2.549,-0.148 -4.717,-0.495 -6.501,-1.042 -1.786,-0.546 -3.428,-1.452 -4.925,-2.72 -1.107,-1.245 -1.751,-2.878 -1.927,-4.902 -0.177,-2.024 0.313,-4.527 1.471,-7.509 1.035,-2.592 2.345,-4.852 3.933,-6.771 1.587,-1.921 3.443,-3.411 5.565,-4.467 2.027,-1.059 4.206,-1.768 6.539,-2.125 2.327,-0.354 4.915,-0.448 7.756,-0.283 2.352,0.139 4.542,0.485 6.574,1.048 0.964,0.265 1.808,0.613 2.542,1.033 L 216.57,0.832 c -2.142,-0.202 -4.333,-0.379 -6.609,-0.51 -21.901,-1.279 -40.308,1.251 -55.229,7.576 -14.918,6.33 -24.865,15.715 -29.833,28.154 -1.491,3.814 -2.292,7.408 -2.41,10.785 l -0.01,-0.005 c -1.426,24.463 14.295,38.245 24.007,44.373 3.897,2.609 7.362,3.901 7.362,3.901 l 4.451,-14.225 1.316,-3.496 c 5.859,1.108 12.375,1.879 19.573,2.298 22.053,1.286 40.539,-1.232 55.458,-7.564 14.916,-6.325 24.78,-15.638 29.591,-27.942 4.806,-12.295 2.514,-22.357 -6.882,-30.181 z"
+ style="fill:url(#linearGradient3027)"/><path
+ id="path18"
+ d="m 269.531,139.499 c -2.511,7.718 -8.23,13.807 -17.156,18.27 -8.926,4.463 -20.223,6.694 -33.891,6.694 -13.484,0 -23.292,-2.208 -29.43,-6.626 -6.136,-4.415 -7.904,-10.528 -5.299,-18.338 l 7.53,-23.291 h 25.663 l -7.252,23.151 c -0.931,2.883 -1.232,5.278 -0.906,7.183 0.326,1.907 1.046,3.417 2.162,4.533 1.394,1.113 2.95,1.88 4.672,2.299 1.72,0.419 3.788,0.629 6.207,0.629 2.417,0 4.742,-0.255 6.974,-0.769 2.231,-0.51 4.275,-1.323 6.138,-2.438 1.858,-1.116 3.508,-2.602 4.951,-4.463 1.44,-1.859 2.626,-4.186 3.557,-6.974 l 7.532,-23.151 h 25.663 l -7.115,23.291 z"
+ style="fill:url(#linearGradient3029)"/><path
+ id="path25"
+ d="m 86.875,140.404 c 2.51,-7.717 0.743,-13.808 -5.301,-18.271 -6.044,-4.463 -15.899,-6.694 -29.567,-6.694 -13.483,0 -24.686,2.21 -33.611,6.625 -8.928,4.417 -14.693,10.53 -17.295,18.34 -2.51,7.72 -0.722,13.786 5.37,18.201 6.089,4.418 15.922,6.626 29.498,6.626 13.575,0 24.826,-2.208 33.753,-6.626 8.924,-4.415 14.642,-10.481 17.153,-18.201 z m -26.082,0.14 c -0.931,2.978 -2.069,5.3 -3.417,6.974 -1.349,1.675 -3.046,3.116 -5.09,4.323 -1.768,1.116 -3.765,1.883 -5.997,2.302 -2.232,0.419 -4.463,0.627 -6.696,0.627 -2.697,0 -4.999,-0.23 -6.903,-0.696 -1.907,-0.465 -3.417,-1.256 -4.533,-2.371 -1.21,-1.116 -1.906,-2.626 -2.092,-4.533 -0.188,-1.904 0.14,-4.114 0.977,-6.625 0.929,-2.88 2.161,-5.275 3.696,-7.183 1.534,-1.904 3.229,-3.417 5.09,-4.533 2.138,-1.115 4.206,-1.882 6.207,-2.301 1.999,-0.419 4.207,-0.627 6.625,-0.627 2.416,0 4.603,0.257 6.555,0.767 1.953,0.512 3.486,1.325 4.603,2.44 1.115,1.116 1.789,2.605 2.021,4.463 0.231,1.86 -0.117,4.185 -1.046,6.973 z"
+ style="fill:url(#linearGradient3031)"/><path
+ id="path32"
+ d="m 310.14,126.807 c 2.928,-0.698 9.041,-1.046 18.339,-1.046 4.833,0 9.506,0.487 14.018,1.465 4.508,0.976 9.042,2.209 13.598,3.696 L 360,119.066 c -2.698,-0.744 -6.625,-1.487 -11.787,-2.231 -5.159,-0.744 -10.669,-1.116 -16.526,-1.116 -17.574,0 -30.405,1.513 -38.493,4.533 -8.089,3.022 -12.879,6.812 -14.366,11.366 -1.115,3.44 -0.348,6.346 2.302,8.717 2.65,2.371 7.322,4.115 14.016,5.229 2.511,0.467 6.624,0.838 12.343,1.117 5.718,0.279 9.46,0.557 11.228,0.836 3.717,0.373 6.205,0.837 7.461,1.396 1.254,0.558 1.695,1.394 1.325,2.511 -0.467,1.303 -1.976,2.279 -4.533,2.928 -2.559,0.652 -6.3,0.977 -11.227,0.977 -0.77,0 -1.513,-0.003 -2.241,-0.007 -1.846,-0.101 -3.858,-0.272 -5.791,-0.476 -2.06,-0.22 -4.118,-0.485 -6.162,-0.795 -4.089,-0.62 -8.132,-1.419 -12.058,-2.439 -3.921,-1.022 -7.734,-2.267 -11.26,-3.813 -0.474,-0.208 -0.932,-0.433 -1.394,-0.654 -2.476,3.979 -5.905,7.451 -10.27,10.396 2.259,1.085 4.539,1.976 6.807,2.742 4.52,1.506 9.034,2.52 13.525,3.266 4.494,0.741 8.969,1.203 13.431,1.472 2.231,0.133 4.459,0.215 6.691,0.248 1.966,0.026 3.882,0.02 5.902,-0.045 12.216,-0.072 22.318,-1.53 30.294,-4.386 8.18,-2.929 13.062,-6.81 14.644,-11.645 1.116,-3.349 0.441,-6.138 -2.021,-8.369 -2.466,-2.231 -6.813,-3.857 -13.041,-4.882 -2.883,-0.371 -5.768,-0.719 -8.647,-1.046 -2.884,-0.324 -5.533,-0.628 -7.951,-0.906 -9.577,-0.65 -14.924,-1.255 -16.039,-1.813 -1.116,-0.558 -1.488,-1.394 -1.116,-2.511 0.467,-1.209 2.164,-2.163 5.094,-2.859 z"
+ style="fill:url(#linearGradient3033)"/><path
+ id="path39"
+ d="m 172.838,122.204 c -6.091,-4.415 -15.924,-6.625 -29.499,-6.625 -13.577,0 -24.826,2.21 -33.751,6.625 -8.926,4.417 -14.4,10.415 -16.911,18.131 l -0.105,0.349 -12.692,39.19 c -5.26,17.631 17.526,24.612 17.526,24.612 l 7.58,-24.612 0.656,-2.106 c 0.592,-1.982 1.192,-3.964 1.781,-5.948 l 1.686,-5.531 c 0.603,-1.832 1.207,-3.662 1.85,-5.481 l 3.979,-10.875 1.993,-5.436 1.429,-3.718 c 0.051,-0.172 0.099,-0.339 0.155,-0.514 0.836,-2.509 1.953,-4.718 3.347,-6.624 1.396,-1.904 3.069,-3.417 5.021,-4.533 1.859,-1.115 3.882,-1.904 6.067,-2.371 2.183,-0.464 4.625,-0.696 7.322,-0.696 2.231,0 4.325,0.208 6.277,0.627 1.952,0.419 3.438,1.186 4.463,2.301 1.301,1.209 2.068,2.65 2.3,4.323 0.231,1.675 -0.117,3.999 -1.046,6.974 -0.931,2.79 -2.116,5.116 -3.557,6.974 -1.442,1.862 -3.091,3.348 -4.951,4.464 -1.861,1.115 -3.905,1.931 -6.136,2.44 -2.231,0.512 -4.558,0.767 -6.973,0.767 -2.419,0 -4.487,-0.208 -6.207,-0.627 -1.721,-0.419 -3.326,-1.186 -4.812,-2.302 -0.112,-0.112 -0.201,-0.247 -0.305,-0.366 l -3.674,10.658 c -0.206,0.613 -0.403,1.228 -0.601,1.842 3.479,0.708 7.507,1.13 12.111,1.256 13.668,0 24.965,-2.231 33.893,-6.694 8.926,-4.464 14.643,-10.552 17.154,-18.271 2.511,-7.719 0.718,-13.786 -5.37,-18.203 z"
+ style="fill:url(#linearGradient3035)"/></g>
+</svg>
--- a/include/opusfile.h
+++ b/include/opusfile.h
@@ -339,7 +339,7 @@
the tag to add (without an '=' character).
\param _value A NUL-terminated UTF-8 containing the corresponding value.
\return 0 on success, or a negative value on failure.
- \retval OP_EFAULT An internal memory allocation failed.*/
+ \retval #OP_EFAULT An internal memory allocation failed.*/
int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
@@ -352,7 +352,7 @@
\param _comment A NUL-terminated UTF-8 string containing the comment in
"TAG=value" form.
\return 0 on success, or a negative value on failure.
- \retval OP_EFAULT An internal memory allocation failed.*/
+ \retval #OP_EFAULT An internal memory allocation failed.*/
int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
@@ -370,7 +370,7 @@
This points directly to data in the #OpusTags structure.
It should not be modified or freed by the application, and
modifications to the structure may invalidate the pointer.
- \retval <code>NULL</code> if no matching tag is found.*/
+ \retval NULL If no matching tag is found.*/
const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
@@ -463,9 +463,9 @@
<code>fclose()</code>.
The differences are that the <code>FILE *</code> arguments have been
replaced with a <code>void *</code>, which is to be used as a pointer to
- whatever internal data these functions might need, that #seek_func and
- #tell_func take and return 64-bit offsets, and that #seek_func *must*
- return -1 if the stream is unseekable.*/
+ whatever internal data these functions might need, that #seek and #tell
+ take and return 64-bit offsets, and that #seek <em>must</em> return -1 if
+ the stream is unseekable.*/
struct OpusFileCallbacks{/**Used to read data from the stream.
This must not be <code>NULL</code>.*/
@@ -657,7 +657,7 @@
The failure code will be #OP_EFAULT if the file could not
be opened, or one of the other failure codes from
op_open_callbacks() otherwise.
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
OP_ARG_NONNULL(1);
@@ -668,7 +668,7 @@
You may pass in <code>NULL</code> if you don't want the
failure code.
See op_open_callbacks() for a full list of failure codes.
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
size_t _size,int *_error);
@@ -683,7 +683,7 @@
You may pass in <code>NULL</code> if you don't want the
failure code.
See op_open_callbacks() for a full list of failure codes.
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
int _flags,int *_error) OP_ARG_NONNULL(1);
@@ -717,7 +717,7 @@
the failure code.
See op_open_callbacks() for a full list of failure
codes.
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url_with_proxy(const char *_url,
int _flags,const char *_proxy_host,unsigned _proxy_port,
const char *_proxy_user,const char *_proxy_pass,int *_error)
@@ -738,7 +738,7 @@
also.
<code><a href="#op_close_func">close()</a></code> may
be <code>NULL</code>, but if it is not, it will be
- called when the #OggOpusFile is destroyed by
+ called when the \c OggOpusFile is destroyed by
op_free().
It will not be called if op_open_callbacks() fails
with an error.
@@ -795,7 +795,7 @@
<dd>The first or last timestamp in a link failed
basic validity checks.</dd>
</dl>
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
@@ -809,7 +809,7 @@
The failure code will be #OP_EFAULT if the file could not
be opened, or one of the other failure codes from
op_open_callbacks() otherwise.
- \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+ \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
OP_ARG_NONNULL(1);
@@ -821,7 +821,7 @@
You may pass in <code>NULL</code> if you don't want the
failure code.
See op_open_callbacks() for a full list of failure codes.
- \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+ \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
size_t _size,int *_error);
@@ -837,7 +837,7 @@
You may pass in <code>NULL</code> if you don't want the
failure code.
See op_open_callbacks() for a full list of failure codes.
- \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+ \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,int _flags,
int *_error) OP_ARG_NONNULL(1);
@@ -872,7 +872,7 @@
the failure code.
See op_open_callbacks() for a full list of failure
codes.
- \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+ \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url_with_proxy(const char *_url,
int _flags,const char *_proxy_host,unsigned _proxy_port,
const char *_proxy_user,const char *_proxy_pass,int *_error)
@@ -897,7 +897,7 @@
also.
<code><a href="#op_close_func">close()</a></code> may
be <code>NULL</code>, but if it is not, it will be
- called when the #OggOpusFile is destroyed by
+ called when the \c OggOpusFile is destroyed by
op_free().
It will not be called if op_open_callbacks() fails
with an error.
@@ -921,7 +921,7 @@
the failure code.
See op_open_callbacks() for a full list of failure
codes.
- \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+ \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
@@ -929,8 +929,8 @@
/**Finish opening a stream partially opened with op_test_callbacks() or one of
the associated convenience functions.
If this function fails, you are still responsible for freeing the
- #OggOpusFile with op_free().
- \param _of The #OggOpusFile to finish opening.
+ \c OggOpusFile with op_free().
+ \param _of The \c OggOpusFile to finish opening.
\return 0 on success, or a negative value on error.
\retval #OP_EREAD An underlying read, seek, or tell operation failed
when it should have succeeded.
@@ -954,8 +954,8 @@
validity checks.*/
int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
-/**Release all memory used by an #OggOpusFile.
- \param _of The #OggOpusFile to free.*/
+/**Release all memory used by an \c OggOpusFile.
+ \param _of The \c OggOpusFile to free.*/
void op_free(OggOpusFile *_of);
/*@}*/
@@ -983,7 +983,7 @@
This function may be called on partially-opened streams, but it will always
return 1.
The actual number of links is not known until the stream is fully opened.
- \param _of The #OggOpusFile from which to retrieve the link count.
+ \param _of The \c OggOpusFile from which to retrieve the link count.
\return For seekable sources, this returns the total number of links in the
whole stream.
For unseekable sources, this always returns 1.*/
@@ -1001,7 +1001,7 @@
successfully able to report the position indicator afterwards.</li>
</ol>
This function may be called on partially-opened streams.
- \param _of The #OggOpusFile whose seekable status is to be returned.
+ \param _of The \c OggOpusFile whose seekable status is to be returned.
\return A non-zero value if seekable, and 0 if unseekable.*/
int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
@@ -1009,7 +1009,7 @@
stream.
This function may be called on partially-opened streams, but it will always
return the serial number of the Opus stream in the first link.
- \param _of The #OggOpusFile from which to retrieve the serial number.
+ \param _of The \c OggOpusFile from which to retrieve the serial number.
\param _li The index of the link whose serial number should be retrieved.
Use a negative number to get the serial number of the current
link.
@@ -1026,7 +1026,7 @@
is provided for convenience.
This function may be called on partially-opened streams, but it will always
return the serial number of the Opus stream in the first link.
- \param _of The #OggOpusFile from which to retrieve the channel count.
+ \param _of The \c OggOpusFile from which to retrieve the channel count.
\param _li The index of the link whose channel count should be retrieved.
Use a negative number to get the channel count of the current
link.
@@ -1040,7 +1040,7 @@
/**Get the total (compressed) size of the stream, or of an individual link in
a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
overhead.
- \param _of The #OggOpusFile from which to retrieve the compressed size.
+ \param _of The \c OggOpusFile from which to retrieve the compressed size.
\param _li The index of the link whose compressed size should be computed.
Use a negative number to get the compressed size of the entire
stream.
@@ -1062,7 +1062,7 @@
Because timestamps in Opus are fixed at 48 kHz, there is no need for a
separate function to convert this to seconds (and leaving it out avoids
introducing floating point to the API, for those that wish to avoid it).
- \param _of The #OggOpusFile from which to retrieve the PCM offset.
+ \param _of The \c OggOpusFile from which to retrieve the PCM offset.
\param _li The index of the link whose PCM length should be computed.
Use a negative number to get the PCM length of the entire stream.
\return The PCM length of the entire stream if \a _li is negative, the PCM
@@ -1077,7 +1077,7 @@
Opus stream.
This function may be called on partially-opened streams, but it will always
return the ID header information of the Opus stream in the first link.
- \param _of The #OggOpusFile from which to retrieve the ID header
+ \param _of The \c OggOpusFile from which to retrieve the ID header
information.
\param _li The index of the link whose ID header information should be
retrieved.
@@ -1091,7 +1091,7 @@
/**Get the comment header information for the given link in a (possibly
chained) Ogg Opus stream.
- \param _of The #OggOpusFile from which to retrieve the comment header
+ \param _of The \c OggOpusFile from which to retrieve the comment header
information.
\param _li The index of the link whose comment header information should be
retrieved.
@@ -1111,7 +1111,7 @@
that the seek target landed in.
Reading more data may advance the link index (even on the first read after a
seek).
- \param _of The #OggOpusFile from which to retrieve the current link index.
+ \param _of The \c OggOpusFile from which to retrieve the current link index.
\return The index of the current link on success, or a negative value on
failture.
For seekable streams, this is a number between 0 and the value
@@ -1126,7 +1126,7 @@
stream.
The stream must be seekable to compute the bitrate.
For unseekable streams, use op_bitrate_instant() to get periodic estimates.
- \param _of The #OggOpusFile from which to retrieve the bitrate.
+ \param _of The \c OggOpusFile from which to retrieve the bitrate.
\param _li The index of the link whose bitrate should be computed.
USe a negative number to get the bitrate of the whole stream.
\return The bitrate on success, or a negative value on error.
@@ -1141,15 +1141,15 @@
This will spike somewhat after a seek or at the start/end of a chain
boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
decoded but not played.
- \param _of The #OggOpusFile from which to retrieve the bitrate.
+ \param _of The \c OggOpusFile from which to retrieve the bitrate.
\return The bitrate, in bits per second, or a negative value on error.
- \retval #OP_EFALSE No data has been decoded since any of the events
+ \retval #OP_FALSE No data has been decoded since any of the events
described above.
\retval #OP_EINVAL The stream was not fully open.*/
opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
/**Obtain the current value of the position indicator for \a _of.
- \param _of The #OggOpusFile from which to retrieve the position indicator.
+ \param _of The \c OggOpusFile from which to retrieve the position indicator.
\return The byte position that is currently being read from.
\retval #OP_EINVAL The stream was not fully open.*/
opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
@@ -1158,7 +1158,7 @@
If the stream is not properly timestamped, this might not increment by the
proper amount between reads, or even return monotonically increasing
values.
- \param _of The #OggOpusFile from which to retrieve the PCM offset.
+ \param _of The \c OggOpusFile from which to retrieve the PCM offset.
\return The PCM offset of the next sample to be read.
\retval #OP_EINVAL The stream was not fully open.*/
ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
@@ -1198,7 +1198,7 @@
This also scans packets to update the PCM cursor.
It will cross a logical bitstream boundary, but only if it can't get any
packets out of the tail of the link to which it seeks.
- \param _of The #OggOpusFile in which to seek.
+ \param _of The \c OggOpusFile in which to seek.
\param _byte_offset The byte position to seek to.
\return 0 on success, or a negative error code on failure.
\retval #OP_EREAD The seek failed.
@@ -1213,7 +1213,7 @@
quickly arrive at the requested position.
This is faster than sample-granularity seeking because it doesn't do the
last bit of decode to find a specific sample.
- \param _of The #OggOpusFile in which to seek.
+ \param _of The \c OggOpusFile in which to seek.
\param _pcm_offset The PCM offset to seek to.
This is in samples at 48 kHz relative to the start of the
stream.
@@ -1227,7 +1227,7 @@
/**Seek to the specified PCM offset, such that decoding will begin at exactly
the requested position.
- \param _of The #OggOpusFile in which to seek.
+ \param _of The \c OggOpusFile in which to seek.
\param _pcm_offset The PCM offset to seek to.
This is in samples at 48 kHz relative to the start of the
stream.
@@ -1292,7 +1292,7 @@
they will simply read too few (rather than reading too many and going
off the end of the buffer).</li>
</ol>
- \param _of The #OggOpusFile from which to read.
+ \param _of The \c OggOpusFile from which to read.
\param[out] _pcm A buffer in which to store the output PCM samples, as
signed native-endian 16-bit values with a nominal
range of <code>[-32768,32767)</code>.
@@ -1365,7 +1365,7 @@
they will simply read too few (rather than reading too many and going
off the end of the buffer).</li>
</ol>
- \param _of The #OggOpusFile from which to read.
+ \param _of The \c OggOpusFile from which to read.
\param[out] _pcm A buffer in which to store the output PCM samples as
signed floats with a nominal range of
<code>[-1.0,1.0]</code>.
@@ -1426,7 +1426,7 @@
in \a _pcm, while the return value is the number of samples <em>per
channel</em>, even though the channel count is known, for consistency with
op_read().
- \param _of The #OggOpusFile from which to read.
+ \param _of The \c OggOpusFile from which to read.
\param[out] _pcm A buffer in which to store the output PCM samples, as
signed native-endian 16-bit values with a nominal
range of <code>[-32768,32767)</code>.
@@ -1479,7 +1479,7 @@
in \a _pcm, while the return value is the number of samples <em>per
channel</em>, even though the channel count is known, for consistency with
op_read_float().
- \param _of The #OggOpusFile from which to read.
+ \param _of The \c OggOpusFile from which to read.
\param[out] _pcm A buffer in which to store the output PCM samples, as
signed floats with a nominal range of
<code>[-1.0,1.0]</code>.