1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
\section{Functions Shared by Encode and Decode}
\label{group__basefuncs}\index{Functions Shared by Encode and Decode@{Functions Shared by Encode and Decode}}
\subsection*{Basic shared functions}
\label{_amgrpb625c22fa07613c734f71c378fe32d7a}
\begin{DoxyCompactItemize}
\item
const char $\ast$ {\bf th\_\-version\_\-string} (void)
\begin{DoxyCompactList}\small\item\em Retrieves a human-\/readable string to identify the library vendor and version. \item\end{DoxyCompactList}\item
ogg\_\-uint32\_\-t {\bf th\_\-version\_\-number} (void)
\begin{DoxyCompactList}\small\item\em Retrieves the library version number. \item\end{DoxyCompactList}\item
ogg\_\-int64\_\-t {\bf th\_\-granule\_\-frame} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{DoxyCompactList}\small\item\em Converts a granule position to an absolute frame index, starting at {\ttfamily 0}. \item\end{DoxyCompactList}\item
double {\bf th\_\-granule\_\-time} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{DoxyCompactList}\small\item\em Converts a granule position to an absolute time in seconds. \item\end{DoxyCompactList}\item
int {\bf th\_\-packet\_\-isheader} (ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Determines whether a Theora packet is a header or not. \item\end{DoxyCompactList}\item
int {\bf th\_\-packet\_\-iskeyframe} (ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Determines whether a theora packet is a key frame or not. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions for manipulating header data}
\label{_amgrp14ef5f819e97c870c128539ed1f334e3}
\begin{DoxyCompactItemize}
\item
void {\bf th\_\-info\_\-init} ({\bf th\_\-info} $\ast$\_\-info)
\begin{DoxyCompactList}\small\item\em Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{DoxyCompactList}\item
void {\bf th\_\-info\_\-clear} ({\bf th\_\-info} $\ast$\_\-info)
\begin{DoxyCompactList}\small\item\em Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{DoxyCompactList}\item
void {\bf th\_\-comment\_\-init} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{DoxyCompactList}\small\item\em Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item
void {\bf th\_\-comment\_\-add} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-comment)
\begin{DoxyCompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item
void {\bf th\_\-comment\_\-add\_\-tag} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, char $\ast$\_\-val)
\begin{DoxyCompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item
char $\ast$ {\bf th\_\-comment\_\-query} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, int \_\-count)
\begin{DoxyCompactList}\small\item\em Look up a comment value by its tag. \item\end{DoxyCompactList}\item
int {\bf th\_\-comment\_\-query\_\-count} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag)
\begin{DoxyCompactList}\small\item\em Look up the number of instances of a tag. \item\end{DoxyCompactList}\item
void {\bf th\_\-comment\_\-clear} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{DoxyCompactList}\small\item\em Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection{Function Documentation}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-add@{th\_\-comment\_\-add}}
\index{th\_\-comment\_\-add@{th\_\-comment\_\-add}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-add}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/ char $\ast$ {\em \_\-comment})}\label{group__basefuncs_ga19a1f7b8032db957df151a34e5ac9272}
Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \begin{DoxyNote}{Note}
Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_ga19a1f7b8032db957df151a34e5ac9272} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_ga6c5edc201ca220a30787ca6c1ddcaeaf} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly.
\end{DoxyNote}
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-comment}]Must be a null-\/terminated UTF-\/8 string containing the comment in \char`\"{}TAG=the value\char`\"{} form. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-add\_\-tag@{th\_\-comment\_\-add\_\-tag}}
\index{th\_\-comment\_\-add\_\-tag@{th\_\-comment\_\-add\_\-tag}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-add\_\-tag}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add\_\-tag ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/ char $\ast$ {\em \_\-tag}, \/ char $\ast$ {\em \_\-val})}\label{group__basefuncs_ga6c5edc201ca220a30787ca6c1ddcaeaf}
Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \begin{DoxyNote}{Note}
Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_ga19a1f7b8032db957df151a34e5ac9272} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_ga6c5edc201ca220a30787ca6c1ddcaeaf} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly.
\end{DoxyNote}
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-tag}]A null-\/terminated string containing the tag associated with the comment. \item[{\em \_\-val}]The corresponding value as a null-\/terminated string. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-clear@{th\_\-comment\_\-clear}}
\index{th\_\-comment\_\-clear@{th\_\-comment\_\-clear}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-clear}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-clear ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_gae736c1afa514947a3feb223143af95e3}
Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. This should be called on a \doxyref{th\_\-comment}{p.}{structth__comment} structure after it is no longer needed. It will free all memory used by the structure members.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to clear. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-init@{th\_\-comment\_\-init}}
\index{th\_\-comment\_\-init@{th\_\-comment\_\-init}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-init}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-init ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_ga6c8ab25988e7ea9d7b1e31a54cf58f09}
Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. This should be called on a freshly allocated \doxyref{th\_\-comment}{p.}{structth__comment} structure before attempting to use it.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to initialize. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-query@{th\_\-comment\_\-query}}
\index{th\_\-comment\_\-query@{th\_\-comment\_\-query}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-query}]{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ th\_\-comment\_\-query ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/ char $\ast$ {\em \_\-tag}, \/ int {\em \_\-count})}\label{group__basefuncs_ga33c8b4f57a03217636d704c2ebb211fa}
Look up a comment value by its tag.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item[{\em \_\-tag}]The tag to look up. \item[{\em \_\-count}]The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use \doxyref{th\_\-comment\_\-query\_\-count()}{p.}{group__basefuncs_ga81d518dc4426f63ceaedcbe2668679fc} to get the legal range for the {\itshape \_\-count\/} parameter. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
A pointer to the queried tag's value. This points directly to data in the \doxyref{th\_\-comment}{p.}{structth__comment} structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer.
\end{DoxyReturn}
\begin{DoxyRetVals}{Return values}
\item[{\em NULL}]If no matching tag is found. \end{DoxyRetVals}
\index{basefuncs@{basefuncs}!th\_\-comment\_\-query\_\-count@{th\_\-comment\_\-query\_\-count}}
\index{th\_\-comment\_\-query\_\-count@{th\_\-comment\_\-query\_\-count}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-comment\_\-query\_\-count}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-comment\_\-query\_\-count ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, \/ char $\ast$ {\em \_\-tag})}\label{group__basefuncs_ga81d518dc4426f63ceaedcbe2668679fc}
Look up the number of instances of a tag. Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to \doxyref{th\_\-comment\_\-query()}{p.}{group__basefuncs_ga33c8b4f57a03217636d704c2ebb211fa} to retrieve all the values for that tag in order.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item[{\em \_\-tag}]The tag to look up. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
The number on instances of this particular tag.
\end{DoxyReturn}
\index{basefuncs@{basefuncs}!th\_\-granule\_\-frame@{th\_\-granule\_\-frame}}
\index{th\_\-granule\_\-frame@{th\_\-granule\_\-frame}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-granule\_\-frame}]{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t th\_\-granule\_\-frame (void $\ast$ {\em \_\-encdec}, \/ ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_ga95b10e76fc4c05d0240ea2dfd9fd62bd}
Converts a granule position to an absolute frame index, starting at {\ttfamily 0}. The granule position is interpreted in the context of a given \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_a843d70bb02563885a8d54b9c1a781729} handle (either will suffice).
\begin{DoxyParams}{Parameters}
\item[{\em \_\-encdec}]A previously allocated \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_a843d70bb02563885a8d54b9c1a781729} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
The absolute frame index corresponding to {\itshape \_\-granpos\/}.
\end{DoxyReturn}
\begin{DoxyRetVals}{Return values}
\item[{\em -\/1}]The given granule position was invalid (i.e. negative). \end{DoxyRetVals}
\index{basefuncs@{basefuncs}!th\_\-granule\_\-time@{th\_\-granule\_\-time}}
\index{th\_\-granule\_\-time@{th\_\-granule\_\-time}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-granule\_\-time}]{\setlength{\rightskip}{0pt plus 5cm}double th\_\-granule\_\-time (void $\ast$ {\em \_\-encdec}, \/ ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_ga707e1e281de788af0df39ef00f3fb432}
Converts a granule position to an absolute time in seconds. The granule position is interpreted in the context of a given \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_a843d70bb02563885a8d54b9c1a781729} handle (either will suffice).
\begin{DoxyParams}{Parameters}
\item[{\em \_\-encdec}]A previously allocated \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_a843d70bb02563885a8d54b9c1a781729} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
The absolute time in seconds corresponding to {\itshape \_\-granpos\/}. This is the \char`\"{}end time\char`\"{} for the frame, or the latest time it should be displayed. It is not the presentation time.
\end{DoxyReturn}
\begin{DoxyRetVals}{Return values}
\item[{\em -\/1}]The given granule position was invalid (i.e. negative). \end{DoxyRetVals}
\index{basefuncs@{basefuncs}!th\_\-info\_\-clear@{th\_\-info\_\-clear}}
\index{th\_\-info\_\-clear@{th\_\-info\_\-clear}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-info\_\-clear}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-clear ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_gab3d6441ab4a4969859ef5fd78a9e3c1c}
Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. This should be called on a \doxyref{th\_\-info}{p.}{structth__info} structure after it is no longer needed.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to clear. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-info\_\-init@{th\_\-info\_\-init}}
\index{th\_\-info\_\-init@{th\_\-info\_\-init}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-info\_\-init}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-init ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_ga430d9c605816a6ca0bdce3a0b965b926}
Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. This should be called on a freshly allocated \doxyref{th\_\-info}{p.}{structth__info} structure before attempting to use it.
\begin{DoxyParams}{Parameters}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to initialize. \end{DoxyParams}
\index{basefuncs@{basefuncs}!th\_\-packet\_\-isheader@{th\_\-packet\_\-isheader}}
\index{th\_\-packet\_\-isheader@{th\_\-packet\_\-isheader}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-packet\_\-isheader}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-isheader (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_ga02f3f38261a9b39452d8a5e6f8737cc1}
Determines whether a Theora packet is a header or not. This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_ga006d01d36fbe64768c571e6a12b7fc50} for that. As per the Theora specification, an empty (0-\/byte) packet is treated as a data packet (a delta frame with no coded blocks).
\begin{DoxyParams}{Parameters}
\item[{\em \_\-op}]An {\ttfamily ogg\_\-packet} containing encoded Theora data. \end{DoxyParams}
\begin{DoxyRetVals}{Return values}
\item[{\em 1}]The packet is a header packet \item[{\em 0}]The packet is a video data packet. \end{DoxyRetVals}
\index{basefuncs@{basefuncs}!th\_\-packet\_\-iskeyframe@{th\_\-packet\_\-iskeyframe}}
\index{th\_\-packet\_\-iskeyframe@{th\_\-packet\_\-iskeyframe}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-packet\_\-iskeyframe}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-iskeyframe (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_gafe95cfd06f0fef413266c9168a66248a}
Determines whether a theora packet is a key frame or not. This function does no verification beyond checking the packet type and key frame bits, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_ga006d01d36fbe64768c571e6a12b7fc50} for that. As per the Theora specification, an empty (0-\/byte) packet is treated as a delta frame (with no coded blocks).
\begin{DoxyParams}{Parameters}
\item[{\em \_\-op}]An {\ttfamily ogg\_\-packet} containing encoded Theora data. \end{DoxyParams}
\begin{DoxyRetVals}{Return values}
\item[{\em 1}]The packet contains a key frame. \item[{\em 0}]The packet contains a delta frame. \item[{\em -\/1}]The packet is not a video data packet. \end{DoxyRetVals}
\index{basefuncs@{basefuncs}!th\_\-version\_\-number@{th\_\-version\_\-number}}
\index{th\_\-version\_\-number@{th\_\-version\_\-number}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-version\_\-number}]{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-uint32\_\-t th\_\-version\_\-number (void)}\label{group__basefuncs_gab723a75c0f95b3eb817f7f769846016b}
Retrieves the library version number. This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. This number is composed of a 16-\/bit major version, 8-\/bit minor version and 8 bit sub-\/version, composed as follows:
\begin{DoxyCode}
(VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
\end{DoxyCode}
\begin{DoxyReturn}{Returns}
the version number.
\end{DoxyReturn}
\index{basefuncs@{basefuncs}!th\_\-version\_\-string@{th\_\-version\_\-string}}
\index{th\_\-version\_\-string@{th\_\-version\_\-string}!basefuncs@{basefuncs}}
\subsubsection[{th\_\-version\_\-string}]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ th\_\-version\_\-string (void)}\label{group__basefuncs_ga04846066738d9f2024fc9961162b2dbc}
Retrieves a human-\/readable string to identify the library vendor and version. \begin{DoxyReturn}{Returns}
the version string.
\end{DoxyReturn}
|
