Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/dither.html @ 169:223a55898ab9 tip default

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents 545efbb81310
children
rev   line source
cannam@85 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
cannam@85 2 <HTML>
cannam@85 3
cannam@85 4 <HEAD>
cannam@85 5 <TITLE>
cannam@85 6 libsndfile : the sf_command function.
cannam@85 7 </TITLE>
cannam@85 8 <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
cannam@85 9 <!-- Another version at the bottom of the page. -->
cannam@85 10 <META NAME="Description" CONTENT="The libsndfile API.">
cannam@85 11 <META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux">
cannam@85 12 <LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all">
cannam@85 13 <LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print">
cannam@85 14 </HEAD>
cannam@85 15
cannam@85 16 <BODY>
cannam@85 17
cannam@85 18 <H1><B>sf_command</B></H1>
cannam@85 19 <PRE>
cannam@85 20
cannam@85 21 int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
cannam@85 22 </PRE>
cannam@85 23 <P>
cannam@85 24 This function allows the caller to retrieve information from or change aspects of the
cannam@85 25 library behaviour.
cannam@85 26 Examples include retrieving a string containing the library version or changing the
cannam@85 27 scaling applied to floating point sample data during read and write.
cannam@85 28 Most of these operations are performed on a per-file basis.
cannam@85 29 </P>
cannam@85 30 <P>
cannam@85 31 The cmd parameter is a integer identifier which is defined in &lt;sndfile.h&gt;.
cannam@85 32 All of the valid command identifiers have names begining with "SFC_".
cannam@85 33 Data is passed to and returned from the library by use of a void pointer.
cannam@85 34 The library will not read or write more than datasize bytes from the void pointer.
cannam@85 35 For some calls no data is required in which case data should be NULL and datasize
cannam@85 36 may be used for some other purpose.
cannam@85 37 </P>
cannam@85 38 <P>
cannam@85 39 The available commands are as follows:
cannam@85 40 </P>
cannam@85 41
cannam@85 42 <CENTER>
cannam@85 43 <TABLE BORDER="0" WIDTH="90%" CELLPADDING="4">
cannam@85 44 <TR>
cannam@85 45 <TD><A HREF="#SFC_GET_LIB_VERSION">SFC_GET_LIB_VERSION</A></TD>
cannam@85 46 <TD>Retrieve the version of the library.</TD>
cannam@85 47 </TR>
cannam@85 48 <TR>
cannam@85 49 <TD><A HREF="#SFC_GET_LOG_INFO">SFC_GET_LOG_INFO</A></TD>
cannam@85 50 <TD>Retrieve the internal per-file operation log.</TD>
cannam@85 51 </TR>
cannam@85 52 <TR>
cannam@85 53 <TD><A HREF="#SFC_CALC_SIGNAL_MAX">SFC_CALC_SIGNAL_MAX</A></TD>
cannam@85 54 <TD>Retrieve the measured maximum signal value.</TD>
cannam@85 55 </TR>
cannam@85 56 <TR>
cannam@85 57 <TD><A HREF="#SFC_CALC_NORM_SIGNAL_MAX">SFC_CALC_NORM_SIGNAL_MAX</A></TD>
cannam@85 58 <TD>Retrieve the measured normalised maximum signal value.</TD>
cannam@85 59 </TR>
cannam@85 60 <TR>
cannam@85 61 <TD><A HREF="#SFC_CALC_MAX_ALL_CHANNELS">SFC_CALC_MAX_ALL_CHANNELS</A></TD>
cannam@85 62 <TD>Calculate peaks for all channels.</TD>
cannam@85 63 </TR>
cannam@85 64 <TR>
cannam@85 65 <TD><A HREF="#SFC_CALC_NORM_MAX_ALL_CHANNELS">SFC_CALC_NORM_MAX_ALL_CHANNELS</A></TD>
cannam@85 66 <TD>Calculate normalised peaks for all channels.</TD>
cannam@85 67 </TR>
cannam@85 68
cannam@85 69 <TR>
cannam@85 70 <TD><A HREF="#SFC_SET_NORM_FLOAT">SFC_SET_NORM_FLOAT</A></TD>
cannam@85 71 <TD>Modify the normalisation behaviour of the floating point reading and writing functions.</TD>
cannam@85 72 </TR>
cannam@85 73 <TR>
cannam@85 74 <TD><A HREF="#SFC_SET_NORM_DOUBLE">SFC_SET_NORM_DOUBLE</A></TD>
cannam@85 75 <TD>Modify the normalisation behaviour of the double precision floating point reading and writing functions.</TD>
cannam@85 76 </TR>
cannam@85 77 <TR>
cannam@85 78 <TD><A HREF="#SFC_GET_NORM_FLOAT">SFC_GET_NORM_FLOAT</A></TD>
cannam@85 79 <TD>Retrieve the current normalisation behaviour of the floating point reading and writing functions.</TD>
cannam@85 80 </TR>
cannam@85 81 <TR>
cannam@85 82 <TD><A HREF="#SFC_GET_NORM_DOUBLE">SFC_GET_NORM_DOUBLE</A></TD>
cannam@85 83 <TD>Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions.</TD>
cannam@85 84 </TR>
cannam@85 85 <TR>
cannam@85 86 <TD><A HREF="#SFC_GET_SIMPLE_FORMAT_COUNT">SFC_GET_SIMPLE_FORMAT_COUNT</A></TD>
cannam@85 87 <TD>Retrieve the number of simple formats supported by libsndfile.</TD>
cannam@85 88 </TR>
cannam@85 89 <TR>
cannam@85 90 <TD><A HREF="#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT</A></TD>
cannam@85 91 <TD>Retrieve information about a simple format.</TD>
cannam@85 92 </TR>
cannam@85 93
cannam@85 94 <TR>
cannam@85 95 <TD><A HREF="#SFC_GET_FORMAT_INFO">SFC_GET_FORMAT_INFO</A></TD>
cannam@85 96 <TD>Retrieve information about a major or subtype format.</TD>
cannam@85 97 </TR>
cannam@85 98
cannam@85 99 <TR>
cannam@85 100 <TD><A HREF="#SFC_GET_FORMAT_MAJOR_COUNT">SFC_GET_FORMAT_MAJOR_COUNT</A></TD>
cannam@85 101 <TD>Retrieve the number of major formats.</TD>
cannam@85 102 </TR>
cannam@85 103 <TR>
cannam@85 104 <TD><A HREF="#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR</A></TD>
cannam@85 105 <TD>Retrieve information about a major format type.</TD>
cannam@85 106 </TR>
cannam@85 107 <TR>
cannam@85 108 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT</A></TD>
cannam@85 109 <TD>Retrieve the number of subformats.</TD>
cannam@85 110 </TR>
cannam@85 111 <TR>
cannam@85 112 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE</A></TD>
cannam@85 113 <TD>Retrieve information about a subformat.</TD>
cannam@85 114 </TR>
cannam@85 115
cannam@85 116 <TR>
cannam@85 117 <TD><A HREF="#SFC_SET_ADD_PEAK_CHUNK">SFC_SET_ADD_PEAK_CHUNK</A></TD>
cannam@85 118 <TD>Switch the code for adding the PEAK chunk to WAV and AIFF files on or off.</TD>
cannam@85 119 </TR>
cannam@85 120
cannam@85 121 <TR>
cannam@85 122 <TD><A HREF="#SFC_UPDATE_HEADER_NOW">SFC_UPDATE_HEADER_NOW</A></TD>
cannam@85 123 <TD>Used when a file is open for write, this command will update the file
cannam@85 124 header to reflect the data written so far.</TD>
cannam@85 125 </TR>
cannam@85 126 <TR>
cannam@85 127 <TD><A HREF="#SFC_SET_UPDATE_HEADER_AUTO">SFC_SET_UPDATE_HEADER_AUTO</A></TD>
cannam@85 128 <TD>Used when a file is open for write, this command will cause the file header
cannam@85 129 to be updated after each write to the file.</TD>
cannam@85 130 </TR>
cannam@85 131
cannam@85 132 <TR>
cannam@85 133 <TD><A HREF="#SFC_FILE_TRUNCATE">SFC_FILE_TRUNCATE</A></TD>
cannam@85 134 <TD>Truncate a file open for write or for read/write.</TD>
cannam@85 135 </TR>
cannam@85 136
cannam@85 137 <TR>
cannam@85 138 <TD><A HREF="#SFC_SET_RAW_START_OFFSET">SFC_SET_RAW_START_OFFSET</A></TD>
cannam@85 139 <TD>Change the data start offset for files opened up as SF_FORMAT_RAW.</TD>
cannam@85 140 </TR>
cannam@85 141
cannam@85 142
cannam@85 143
cannam@85 144 <!--
cannam@85 145 <TR>
cannam@85 146 <TD><A HREF="#add-dither">add dither</A></TD>
cannam@85 147 <TD>Add dither to output on write.</TD>
cannam@85 148 </TR>
cannam@85 149 -->
cannam@85 150 </TABLE>
cannam@85 151 </CENTER>
cannam@85 152
cannam@85 153 <BR><BR>
cannam@85 154
cannam@85 155 <HR>
cannam@85 156
cannam@85 157 <!-- ========================================================================= -->
cannam@85 158 <A NAME="SFC_GET_LIB_VERSION"></A>
cannam@85 159 <H2><BR><B>SFC_GET_LIB_VERSION</B></H2>
cannam@85 160 <P>
cannam@85 161 Retrieve the version of the library as a string.
cannam@85 162 </P>
cannam@85 163 <P>
cannam@85 164 Parameters:
cannam@85 165 <PRE>
cannam@85 166 sndfile : Not used
cannam@85 167 cmd : SFC_GET_LIB_VERSION
cannam@85 168 data : A pointer to a char buffer
cannam@85 169 datasize : The size of the the buffer
cannam@85 170 </PRE>
cannam@85 171 <P>
cannam@85 172 Example:
cannam@85 173 </P>
cannam@85 174 <PRE>
cannam@85 175 char buffer [128] ;
cannam@85 176 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
cannam@85 177 </PRE>
cannam@85 178
cannam@85 179 <DL>
cannam@85 180 <DT>Return value:</DT>
cannam@85 181 <DD><DD>This call will return the length of the retrieved version string.
cannam@85 182 </DL>
cannam@85 183 <DL>
cannam@85 184 <DT>Notes:</DT>
cannam@85 185 <DD>
cannam@85 186 The string returned in the buffer passed to this function will not overflow
cannam@85 187 the buffer and will always be null terminated .
cannam@85 188 </DL>
cannam@85 189
cannam@85 190 <!-- ========================================================================= -->
cannam@85 191 <A NAME="SFC_GET_LOG_INFO"></A>
cannam@85 192 <H2><BR><B>SFC_GET_LOG_INFO</B></H2>
cannam@85 193 <P>
cannam@85 194 Retrieve the log buffer generated when opening a file as a string. This log
cannam@85 195 buffer can often contain a good reason for why libsndfile failed to open a
cannam@85 196 particular file.
cannam@85 197 </P>
cannam@85 198 <P>
cannam@85 199 Parameters:
cannam@85 200 <PRE>
cannam@85 201 sndfile : A valid SNDFILE* pointer
cannam@85 202 cmd : SFC_GET_LOG_INFO
cannam@85 203 data : A pointer to a char buffer
cannam@85 204 datasize : The size of the the buffer
cannam@85 205 </PRE>
cannam@85 206 <P>
cannam@85 207 Example:
cannam@85 208 </P>
cannam@85 209 <PRE>
cannam@85 210 char buffer [2048] ;
cannam@85 211 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
cannam@85 212 </PRE>
cannam@85 213
cannam@85 214 <DL>
cannam@85 215 <DT>Return value:</DT>
cannam@85 216 <DD><DD>This call will return the length of the retrieved version string.
cannam@85 217 </DL>
cannam@85 218 <DL>
cannam@85 219 <DT>Notes:</DT>
cannam@85 220 <DD>
cannam@85 221 The string returned in the buffer passed to this function will not overflow
cannam@85 222 the buffer and will always be null terminated .
cannam@85 223 </DL>
cannam@85 224
cannam@85 225 <!-- ========================================================================= -->
cannam@85 226 <A NAME="SFC_CALC_SIGNAL_MAX"></A>
cannam@85 227 <H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2>
cannam@85 228 <P>
cannam@85 229 Retrieve the measured maximum signal value. This involves reading through
cannam@85 230 the whole file which can be slow on large files.
cannam@85 231 </P>
cannam@85 232 <P>
cannam@85 233 Parameters:
cannam@85 234 <PRE>
cannam@85 235 sndfile : A valid SNDFILE* pointer
cannam@85 236 cmd : SFC_CALC_SIGNAL_MAX
cannam@85 237 data : A pointer to a double
cannam@85 238 datasize : sizeof (double)
cannam@85 239 </PRE>
cannam@85 240 <P>
cannam@85 241 Example:
cannam@85 242 </P>
cannam@85 243 <PRE>
cannam@85 244 double max_val ;
cannam@85 245 sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
cannam@85 246 </PRE>
cannam@85 247
cannam@85 248 <DL>
cannam@85 249 <DT>Return value:</DT>
cannam@85 250 <DD><DD>Zero on success, non-zero otherwise.
cannam@85 251 </DL>
cannam@85 252
cannam@85 253 <!-- ========================================================================= -->
cannam@85 254 <A NAME="SFC_CALC_NORM_SIGNAL_MAX"></A>
cannam@85 255 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2>
cannam@85 256 <P>
cannam@85 257 Retrieve the measured normailised maximum signal value. This involves reading
cannam@85 258 through the whole file which can be slow on large files.
cannam@85 259 </P>
cannam@85 260 <P>
cannam@85 261 Parameters:
cannam@85 262 <PRE>
cannam@85 263 sndfile : A valid SNDFILE* pointer
cannam@85 264 cmd : SFC_CALC_NORM_SIGNAL_MAX
cannam@85 265 data : A pointer to a double
cannam@85 266 datasize : sizeof (double)
cannam@85 267 </PRE>
cannam@85 268 <P>
cannam@85 269 Example:
cannam@85 270 </P>
cannam@85 271 <PRE>
cannam@85 272 double max_val ;
cannam@85 273 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
cannam@85 274 </PRE>
cannam@85 275
cannam@85 276 <DL>
cannam@85 277 <DT>Return value:</DT>
cannam@85 278 <DD><DD>Zero on success, non-zero otherwise.
cannam@85 279 </DL>
cannam@85 280
cannam@85 281 <!-- ========================================================================= -->
cannam@85 282 <A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A>
cannam@85 283 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2>
cannam@85 284 <P>
cannam@85 285 Calculate peaks for all channels. This involves reading through
cannam@85 286 the whole file which can be slow on large files.
cannam@85 287 </P>
cannam@85 288 <P>
cannam@85 289 Parameters:
cannam@85 290 <PRE>
cannam@85 291 sndfile : A valid SNDFILE* pointer
cannam@85 292 cmd : SFC_CALC_MAX_ALL_CHANNELS
cannam@85 293 data : A pointer to a double
cannam@85 294 datasize : sizeof (double) * number_of_channels
cannam@85 295 </PRE>
cannam@85 296 <P>
cannam@85 297 Example:
cannam@85 298 </P>
cannam@85 299 <PRE>
cannam@85 300 double peaks [number_of_channels] ;
cannam@85 301 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
cannam@85 302 </PRE>
cannam@85 303 <DL>
cannam@85 304 <DT>Return value:</DT>
cannam@85 305 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
cannam@85 306 </DL>
cannam@85 307
cannam@85 308
cannam@85 309 <!-- ========================================================================= -->
cannam@85 310 <A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
cannam@85 311 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2>
cannam@85 312 <P>
cannam@85 313 Calculate normalised peaks for all channels. This involves reading through
cannam@85 314 the whole file which can be slow on large files.
cannam@85 315 </P>
cannam@85 316 <P>
cannam@85 317 Parameters:
cannam@85 318 <PRE>
cannam@85 319 sndfile : A valid SNDFILE* pointer
cannam@85 320 cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
cannam@85 321 data : A pointer to a double
cannam@85 322 datasize : sizeof (double) * number_of_channels
cannam@85 323 </PRE>
cannam@85 324 <P>
cannam@85 325 Example:
cannam@85 326 </P>
cannam@85 327 <PRE>
cannam@85 328 double peaks [number_of_channels] ;
cannam@85 329 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
cannam@85 330 </PRE>
cannam@85 331 <DL>
cannam@85 332 <DT>Return value:</DT>
cannam@85 333 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
cannam@85 334 </DL>
cannam@85 335
cannam@85 336
cannam@85 337
cannam@85 338
cannam@85 339
cannam@85 340 <!-- ========================================================================= -->
cannam@85 341 <!--
cannam@85 342 <A NAME="read-text"></A>
cannam@85 343 <H2><BR><B>Read text</B></H2>
cannam@85 344 <P>
cannam@85 345 Many sound file formats contain allow the inclusion of a text string describing the nature
cannam@85 346 of the file. If a file contains such a string, this functions will return it to the caller.
cannam@85 347 </P>
cannam@85 348 <P>
cannam@85 349 It should be noted that the way the string is added to the file is file format dependant
cannam@85 350 but that any string added with <A HREF="#write-text">write text</A> will be returned by
cannam@85 351 <A HREF="#read-text">read text</A>.
cannam@85 352 </P>
cannam@85 353 <P>
cannam@85 354 <P>
cannam@85 355 Parameters:
cannam@85 356 </P>
cannam@85 357 <PRE>
cannam@85 358 sndfile : A valid SNDFILE* pointer
cannam@85 359 cmd : The text string "read text".
cannam@85 360 data : A pointer to a char buffer.
cannam@85 361 datasize : The size of the the buffer.
cannam@85 362 </PRE>
cannam@85 363 <P>
cannam@85 364 Example:
cannam@85 365 </P>
cannam@85 366 <PRE>
cannam@85 367 char buffer [128] ;
cannam@85 368 sf_command (sndfile, "read text", buffer, sizeof (buffer)) ;
cannam@85 369 </PRE>
cannam@85 370 <DL>
cannam@85 371 <DT>Return value:</DT>
cannam@85 372 <DD>If a text string is found, this call will return the length of the retrieved text
cannam@85 373 string.
cannam@85 374 <DD>If no text string is found, zero will be returned and the first element in the
cannam@85 375 buffer will be set to the null character.
cannam@85 376 <DT>Notes:</DT>
cannam@85 377 <DD>The string returned in the buffer passed to this function will not overflow
cannam@85 378 the buffer and will be correctly null terminated .
cannam@85 379 </DL>
cannam@85 380
cannam@85 381 <A NAME="write-text"></A>
cannam@85 382 <H2><BR><B>Write text</B></H2>
cannam@85 383 <P>
cannam@85 384 Add a text string to a file. The text string added can be retrieved when the file is
cannam@85 385 read using <A HREF="#read-text">read text</A>.
cannam@85 386 </P>
cannam@85 387 <P>
cannam@85 388 Parameters:
cannam@85 389 </P>
cannam@85 390 <PRE>
cannam@85 391 sndfile : A valid SNDFILE* pointer
cannam@85 392 cmd : The text string "write text".
cannam@85 393 data : A pointer to the string to be added.
cannam@85 394 datasize : Not used.
cannam@85 395 </PRE>
cannam@85 396 <P>
cannam@85 397 Example:
cannam@85 398 </P>
cannam@85 399 <PRE>
cannam@85 400 char text = "The sound of one hand clapping." ;
cannam@85 401 sf_command (sndfile, "write text", text, strlen (text)) ;
cannam@85 402 </PRE>
cannam@85 403 <DL>
cannam@85 404 <DT>Return value: </DT>
cannam@85 405 <DD>If the current file format allows the addition of text strings, the string will
cannam@85 406 be added and the length of the string will be returned.
cannam@85 407 <DD>If the file format does not allow the addition of text strings zero will be returned.
cannam@85 408 <DD>If this function is called after the file is openned but before
cannam@85 409 </DL>
cannam@85 410 -->
cannam@85 411
cannam@85 412
cannam@85 413 <!-- ========================================================================= -->
cannam@85 414 <A NAME="SFC_SET_NORM_FLOAT"></A>
cannam@85 415 <H2><BR><B>SFC_SET_NORM_FLOAT</B></H2>
cannam@85 416 <P>
cannam@85 417 This command only affects data read from or written to using the floating point functions:
cannam@85 418 </P>
cannam@85 419 <PRE>
cannam@85 420 size_t <A HREF="api.html#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
cannam@85 421 size_t <A HREF="api.html#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
cannam@85 422
cannam@85 423 size_t <A HREF="api.html#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
cannam@85 424 size_t <A HREF="api.html#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
cannam@85 425 </PRE>
cannam@85 426 <P>
cannam@85 427 Parameters:
cannam@85 428 </P>
cannam@85 429 <PRE>
cannam@85 430 sndfile : A valid SNDFILE* pointer
cannam@85 431 cmd : SFC_SET_NORM_FLOAT
cannam@85 432 data : NULL
cannam@85 433 datasize : SF_TRUE or SF_FALSE
cannam@85 434 </PRE>
cannam@85 435 <P>
cannam@85 436 For read operations setting normalisation to SF_TRUE means that the data from all
cannam@85 437 subsequent reads will be be normalised to the range [-1.0, 1.0].
cannam@85 438 </P>
cannam@85 439 <P>
cannam@85 440 For write operations, setting normalisation to SF_TRUE means than all data supplied
cannam@85 441 to the float write functions should be in the range [-1.0, 1.0] and will be scaled
cannam@85 442 for the file format as necessary.
cannam@85 443 </P>
cannam@85 444 <P>
cannam@85 445 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
cannam@85 446 </P>
cannam@85 447 <P>
cannam@85 448 Example:
cannam@85 449 </P>
cannam@85 450 <PRE>
cannam@85 451 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
cannam@85 452
cannam@85 453 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
cannam@85 454 </PRE>
cannam@85 455 <DL>
cannam@85 456 <DT>Return value: </DT>
cannam@85 457 <DD>Returns 1 on success or 0 for failure.
cannam@85 458 </DL>
cannam@85 459
cannam@85 460 <!-- ========================================================================= -->
cannam@85 461 <A NAME="SFC_SET_NORM_DOUBLE"></A>
cannam@85 462 <H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2>
cannam@85 463 <P>
cannam@85 464 This command only affects data read from or written to using the double precision
cannam@85 465 floating point functions:
cannam@85 466 </P>
cannam@85 467 <PRE>
cannam@85 468 size_t <A HREF="api.html#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
cannam@85 469 size_t <A HREF="api.html#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
cannam@85 470
cannam@85 471 size_t <A HREF="api.html#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
cannam@85 472 size_t <A HREF="api.html#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
cannam@85 473 </PRE>
cannam@85 474 <P>
cannam@85 475 Parameters:
cannam@85 476 </P>
cannam@85 477 <PRE>
cannam@85 478 sndfile : A valid SNDFILE* pointer
cannam@85 479 cmd : SFC_SET_NORM_DOUBLE
cannam@85 480 data : NULL
cannam@85 481 datasize : SF_TRUE or SF_FALSE
cannam@85 482 </PRE>
cannam@85 483 <P>
cannam@85 484 For read operations setting normalisation to SF_TRUE means that the data
cannam@85 485 from all subsequent reads will be be normalised to the range [-1.0, 1.0].
cannam@85 486 </P>
cannam@85 487 <P>
cannam@85 488 For write operations, setting normalisation to SF_TRUE means than all data supplied
cannam@85 489 to the double write functions should be in the range [-1.0, 1.0] and will be scaled
cannam@85 490 for the file format as necessary.
cannam@85 491 </P>
cannam@85 492 <P>
cannam@85 493 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
cannam@85 494 </P>
cannam@85 495 <P>
cannam@85 496 Example:
cannam@85 497 </P>
cannam@85 498 <PRE>
cannam@85 499 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
cannam@85 500
cannam@85 501 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
cannam@85 502 </PRE>
cannam@85 503 <DL>
cannam@85 504 <DT>Return value: </DT>
cannam@85 505 <DD>Returns 1 on success or 0 for failure.
cannam@85 506 </DL>
cannam@85 507
cannam@85 508 <!-- ========================================================================= -->
cannam@85 509 <A NAME="SFC_GET_NORM_FLOAT"></A>
cannam@85 510 <H2><BR><B>SFC_GET_NORM_FLOAT</B></H2>
cannam@85 511 <P>
cannam@85 512 Retrieve the current float normalisation mode.
cannam@85 513 </P>
cannam@85 514 <P>
cannam@85 515 Parameters:
cannam@85 516 </P>
cannam@85 517 <PRE>
cannam@85 518 sndfile : A valid SNDFILE* pointer
cannam@85 519 cmd : SFC_GET_NORM_FLOAT
cannam@85 520 data : NULL
cannam@85 521 datasize : anything
cannam@85 522 </PRE>
cannam@85 523 <P>
cannam@85 524 Example:
cannam@85 525 </P>
cannam@85 526 <PRE>
cannam@85 527 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
cannam@85 528 </PRE>
cannam@85 529 <DL>
cannam@85 530 <DT>Return value: </DT>
cannam@85 531 <DD>Returns TRUE if normaisation is on and FALSE otherwise.
cannam@85 532 </DL>
cannam@85 533
cannam@85 534 <!-- ========================================================================= -->
cannam@85 535 <A NAME="SFC_GET_NORM_DOUBLE"></A>
cannam@85 536 <H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2>
cannam@85 537 <P>
cannam@85 538 Retrieve the current float normalisation mode.
cannam@85 539 </P>
cannam@85 540 <P>
cannam@85 541 Parameters:
cannam@85 542 </P>
cannam@85 543 <PRE>
cannam@85 544 sndfile : A valid SNDFILE* pointer
cannam@85 545 cmd : SFC_GET_NORM_DOUBLE
cannam@85 546 data : NULL
cannam@85 547 datasize : anything
cannam@85 548 </PRE>
cannam@85 549 <P>
cannam@85 550 Example:
cannam@85 551 </P>
cannam@85 552 <PRE>
cannam@85 553 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
cannam@85 554 </PRE>
cannam@85 555 <DL>
cannam@85 556 <DT>Return value: </DT>
cannam@85 557 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
cannam@85 558 </DL>
cannam@85 559
cannam@85 560 <!-- ========================================================================= -->
cannam@85 561 <A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A>
cannam@85 562 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2>
cannam@85 563 <P>
cannam@85 564 Retrieve the number of simple formats supported by libsndfile.
cannam@85 565 </P>
cannam@85 566 <P>
cannam@85 567 Parameters:
cannam@85 568 </P>
cannam@85 569 <PRE>
cannam@85 570 sndfile : Not used.
cannam@85 571 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
cannam@85 572 data : a pointer to an int
cannam@85 573 datasize : sizeof (int)
cannam@85 574 </PRE>
cannam@85 575 <P>
cannam@85 576 Example:
cannam@85 577 </P>
cannam@85 578 <PRE>
cannam@85 579 int count ;
cannam@85 580 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
cannam@85 581 </PRE>
cannam@85 582 <DL>
cannam@85 583 <DT>Return value: </DT>
cannam@85 584 <DD>0
cannam@85 585 </DL>
cannam@85 586
cannam@85 587 <!-- ========================================================================= -->
cannam@85 588 <A NAME="SFC_GET_SIMPLE_FORMAT"></A>
cannam@85 589 <H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2>
cannam@85 590 <P>
cannam@85 591 Retrieve information about a simple format.
cannam@85 592 </P>
cannam@85 593 <P>
cannam@85 594 Parameters:
cannam@85 595 </P>
cannam@85 596 <PRE>
cannam@85 597 sndfile : Not used.
cannam@85 598 cmd : SFC_GET_SIMPLE_FORMAT
cannam@85 599 data : a pointer to an SF_FORMAT_INFO struct
cannam@85 600 datasize : sizeof (SF_FORMAT_INFO)
cannam@85 601 </PRE>
cannam@85 602 <P>
cannam@85 603 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
cannam@85 604 </P>
cannam@85 605 <PRE>
cannam@85 606 typedef struct
cannam@85 607 { int format ;
cannam@85 608 const char *name ;
cannam@85 609 const char *extension ;
cannam@85 610 } SF_FORMAT_INFO ;
cannam@85 611 </PRE>
cannam@85 612 <P>
cannam@85 613 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
cannam@85 614 field should be the format number (ie 0 <= format <= count value obtained using
cannam@85 615 SF_GET_SIMPLE_FORMAT_COUNT).
cannam@85 616 </P>
cannam@85 617 <P>
cannam@85 618 Example:
cannam@85 619 </P>
cannam@85 620 <PRE>
cannam@85 621 SF_FORMAT_INFO format_info ;
cannam@85 622 int k, count ;
cannam@85 623
cannam@85 624 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
cannam@85 625
cannam@85 626 for (k = 0 ; k < count ; k++)
cannam@85 627 { format_info.format = k ;
cannam@85 628 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &amp;format_info, sizeof (format_info)) ;
cannam@85 629 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@85 630 } ;
cannam@85 631 </PRE>
cannam@85 632 <DL>
cannam@85 633 <DT>Return value: </DT>
cannam@85 634 <DD>0 on success and non-zero otherwise.
cannam@85 635 <DD>The value of the format field of the SF_FORMAT_INFO struct will be an value which
cannam@85 636 can be placed in the format field of an SF_INFO struct when a file is to be opened
cannam@85 637 for write.
cannam@85 638 <DD>The name field will contain a char* pointer to the name of the string ie "WAV (Microsoft 16 bit PCM)".
cannam@85 639 <DD>The extention field will contain the most commonly used file extension for that file type.
cannam@85 640 </DL>
cannam@85 641
cannam@85 642 <!-- ========================================================================= -->
cannam@85 643 <A NAME="SFC_GET_FORMAT_INFO"></A>
cannam@85 644 <H2><BR><B>SFC_GET_FORMAT_INFO</B></H2>
cannam@85 645 <P>
cannam@85 646 Retrieve information about a major or subtype format.
cannam@85 647 </P>
cannam@85 648 <P>
cannam@85 649 Parameters:
cannam@85 650 </P>
cannam@85 651 <PRE>
cannam@85 652 sndfile : Not used.
cannam@85 653 cmd : SFC_GET_FORMAT_INFO
cannam@85 654 data : a pointer to an SF_FORMAT_INFO struct
cannam@85 655 datasize : sizeof (SF_FORMAT_INFO)
cannam@85 656 </PRE>
cannam@85 657 <P>
cannam@85 658 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
cannam@85 659 </P>
cannam@85 660 <PRE>
cannam@85 661 typedef struct
cannam@85 662 { int format ;
cannam@85 663 const char *name ;
cannam@85 664 const char *extension ;
cannam@85 665 } SF_FORMAT_INFO ;
cannam@85 666 </PRE>
cannam@85 667 <P>
cannam@85 668 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
cannam@85 669 examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct
cannam@85 670 is filled in with information about the given major type.
cannam@85 671 If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a
cannam@85 672 valid subtype format then the struct is filled in with information about the given
cannam@85 673 subtype.
cannam@85 674 </P>
cannam@85 675 <P>
cannam@85 676 Example:
cannam@85 677 </P>
cannam@85 678 <PRE>
cannam@85 679 SF_FORMAT_INFO format_info ;
cannam@85 680
cannam@85 681 format_info.format = SF_FORMAT_WAV ;
cannam@85 682 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
cannam@85 683 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@85 684
cannam@85 685 format_info.format = SF_FORMAT_ULAW ;
cannam@85 686 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
cannam@85 687 printf ("%08x %s\n", format_info.format, format_info.name) ;
cannam@85 688 </PRE>
cannam@85 689 <DL>
cannam@85 690 <DT>Return value: </DT>
cannam@85 691 <DD>0 on success and non-zero otherwise.
cannam@85 692 </DL>
cannam@85 693 <!-- ========================================================================= -->
cannam@85 694 <A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A>
cannam@85 695 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2>
cannam@85 696 <P>
cannam@85 697 Retrieve the number of major formats.
cannam@85 698 </P>
cannam@85 699 <P>
cannam@85 700 Parameters:
cannam@85 701 </P>
cannam@85 702 <PRE>
cannam@85 703 sndfile : Not used.
cannam@85 704 cmd : SFC_GET_FORMAT_MAJOR_COUNT
cannam@85 705 data : a pointer to an int
cannam@85 706 datasize : sizeof (int)
cannam@85 707 </PRE>
cannam@85 708 <P>
cannam@85 709 Example:
cannam@85 710 </P>
cannam@85 711 <PRE>
cannam@85 712 int count ;
cannam@85 713 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
cannam@85 714 </PRE>
cannam@85 715 <DL>
cannam@85 716 <DT>Return value: </DT>
cannam@85 717 <DD>0
cannam@85 718 </DL>
cannam@85 719
cannam@85 720 <!-- ========================================================================= -->
cannam@85 721 <A NAME="SFC_GET_FORMAT_MAJOR"></A>
cannam@85 722 <H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2>
cannam@85 723 <P>
cannam@85 724 Retrieve information about a major format type.
cannam@85 725 </P>
cannam@85 726 <P>
cannam@85 727 Parameters:
cannam@85 728 </P>
cannam@85 729 <PRE>
cannam@85 730 sndfile : Not used.
cannam@85 731 cmd : SFC_GET_FORMAT_MAJOR
cannam@85 732 data : a pointer to an SF_FORMAT_INFO struct
cannam@85 733 datasize : sizeof (SF_FORMAT_INFO)
cannam@85 734 </PRE>
cannam@85 735 <P>
cannam@85 736 Example:
cannam@85 737 </P>
cannam@85 738 <PRE>
cannam@85 739 SF_FORMAT_INFO format_info ;
cannam@85 740 int k, count ;
cannam@85 741
cannam@85 742 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
cannam@85 743
cannam@85 744 for (k = 0 ; k < count ; k++)
cannam@85 745 { format_info.format = k ;
cannam@85 746 sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &amp;format_info, sizeof (format_info)) ;
cannam@85 747 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@85 748 } ;
cannam@85 749 </PRE>
cannam@85 750 <P>
cannam@85 751 For a more comprehensive example, see the program list_formats.c in the examples/
cannam@85 752 directory of the libsndfile source code distribution.
cannam@85 753 </P>
cannam@85 754 <DL>
cannam@85 755 <DT>Return value: </DT>
cannam@85 756 <DD>0 on success and non-zero otherwise.
cannam@85 757 <DD>The value of the format field will one of the major format identifiers suc as SF_FORMAT_WAV
cannam@85 758 SF_FORMAT_AIFF.
cannam@85 759 <DD>The name field will contain a char* pointer to the name of the string ie "WAV (Microsoft)".
cannam@85 760 <DD>The extention field will contain the most commonly used file extension for that file type.
cannam@85 761 </DL>
cannam@85 762
cannam@85 763 <!-- ========================================================================= -->
cannam@85 764 <A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
cannam@85 765 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2>
cannam@85 766 <P>
cannam@85 767 Retrieve the number of subformats.
cannam@85 768 </P>
cannam@85 769 <P>
cannam@85 770 Parameters:
cannam@85 771 </P>
cannam@85 772 <PRE>
cannam@85 773 sndfile : Not used.
cannam@85 774 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
cannam@85 775 data : a pointer to an int
cannam@85 776 datasize : sizeof (int)
cannam@85 777 </PRE>
cannam@85 778 <P>
cannam@85 779 Example:
cannam@85 780 </P>
cannam@85 781 <PRE>
cannam@85 782 int count ;
cannam@85 783 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
cannam@85 784 </PRE>
cannam@85 785 <DL>
cannam@85 786 <DT>Return value: </DT>
cannam@85 787 <DD>0
cannam@85 788 </DL>
cannam@85 789
cannam@85 790 <!-- ========================================================================= -->
cannam@85 791 <A NAME="SFC_GET_FORMAT_SUBTYPE"></A>
cannam@85 792 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2>
cannam@85 793 <P>
cannam@85 794 Retrieve information about a subformat.
cannam@85 795 </P>
cannam@85 796 <P>
cannam@85 797 Parameters:
cannam@85 798 </P>
cannam@85 799 <PRE>
cannam@85 800 sndfile : Not used.
cannam@85 801 cmd : SFC_GET_FORMAT_SUBTYPE
cannam@85 802 data : a pointer to an SF_FORMAT_INFO struct
cannam@85 803 datasize : sizeof (SF_FORMAT_INFO)
cannam@85 804 </PRE>
cannam@85 805 <P>
cannam@85 806 Example:
cannam@85 807 </P>
cannam@85 808 <PRE>
cannam@85 809 SF_FORMAT_INFO format_info ;
cannam@85 810 int k, count ;
cannam@85 811
cannam@85 812 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
cannam@85 813
cannam@85 814 /* Retrieve all the subtypes supported by the WAV format. */
cannam@85 815 for (k = 0 ; k < count ; k++)
cannam@85 816 { format_info.format = k ;
cannam@85 817 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
cannam@85 818 if (! sf_format_check (format.info | SF_FORMAT_WAV))
cannam@85 819 continue ;
cannam@85 820 printf ("%08x %s\n", format_info.format, format_info.name) ;
cannam@85 821 } ;
cannam@85 822 </PRE>
cannam@85 823 <P>
cannam@85 824 For a more comprehensive example, see the program list_formats.c in the examples/
cannam@85 825 directory of the libsndfile source code distribution.
cannam@85 826 </P>
cannam@85 827 <DL>
cannam@85 828 <DT>Return value: </DT>
cannam@85 829 <DD>0 on success and non-zero otherwise.
cannam@85 830 <DD>The value of the format field will one of the major format identifiers such as SF_FORMAT_WAV
cannam@85 831 SF_FORMAT_AIFF.
cannam@85 832 <DD>The name field will contain a char* pointer to the name of the string; for instance
cannam@85 833 "WAV (Microsoft)" or "AIFF (Apple/SGI)".
cannam@85 834 <DD>The extention field will be a NULL pointer.
cannam@85 835 </DL>
cannam@85 836
cannam@85 837 <!-- ========================================================================= -->
cannam@85 838 <A NAME="SFC_SET_ADD_PEAK_CHUNK"></A>
cannam@85 839 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2>
cannam@85 840 <P>
cannam@85 841 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
cannam@85 842 or SF_FORMAT_DOUBLE) have a PEAK chunk.
cannam@85 843 By using this command, the addition of a PEAK chunk can be turned on or off.
cannam@85 844 </P>
cannam@85 845 <P>
cannam@85 846 Note : This call must be made before any data is written to the file.
cannam@85 847 </P>
cannam@85 848 <P>
cannam@85 849 Parameters:
cannam@85 850 <PRE>
cannam@85 851 sndfile : A valid SNDFILE* pointer
cannam@85 852 cmd : SFC_SET_ADD_PEAK_CHUNK
cannam@85 853 data : Not used (should be NULL)
cannam@85 854 datasize : TRUE or FALSE.
cannam@85 855 </PRE>
cannam@85 856 <P>
cannam@85 857 Example:
cannam@85 858 </P>
cannam@85 859 <PRE>
cannam@85 860 /* Turn on the PEAK chunk. */
cannam@85 861 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
cannam@85 862
cannam@85 863 /* Turn off the PEAK chunk. */
cannam@85 864 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
cannam@85 865 </PRE>
cannam@85 866 <DL>
cannam@85 867 <DT>Return value:</DT>
cannam@85 868 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
cannam@85 869 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
cannam@85 870 </DL>
cannam@85 871
cannam@85 872 <!-- ========================================================================= -->
cannam@85 873 <A NAME="SFC_UPDATE_HEADER_NOW"></A>
cannam@85 874 <H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2>
cannam@85 875 <P>
cannam@85 876 The header of an audio file is normally written by libsndfile when the file is
cannam@85 877 closed using <B>sf_close()</B>.
cannam@85 878 </P>
cannam@85 879 <P>
cannam@85 880 There are however situations where large files are being generated and it would
cannam@85 881 be nice to have valid data in the header before the file is complete.
cannam@85 882 Using this command will update the file header to reflect the amount of data written
cannam@85 883 to the file so far.
cannam@85 884 Other programs opening the file for read (before any more data is written) will
cannam@85 885 then read a valid sound file header.
cannam@85 886 </P>
cannam@85 887 <P>
cannam@85 888 Parameters:
cannam@85 889 <PRE>
cannam@85 890 sndfile : A valid SNDFILE* pointer
cannam@85 891 cmd : SFC_UPDATE_HEADER_NOW
cannam@85 892 data : Not used (should be NULL)
cannam@85 893 datasize : Not used.
cannam@85 894 </PRE>
cannam@85 895 <P>
cannam@85 896 Example:
cannam@85 897 </P>
cannam@85 898 <PRE>
cannam@85 899 /* Update the header now. */
cannam@85 900 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
cannam@85 901 </PRE>
cannam@85 902 <DL>
cannam@85 903 <DT>Return value:</DT>
cannam@85 904 <DD>0
cannam@85 905 </DL>
cannam@85 906
cannam@85 907 <!-- ========================================================================= -->
cannam@85 908 <A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A>
cannam@85 909 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2>
cannam@85 910 <P>
cannam@85 911 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
cannam@85 912 to the <B>sf_write*</B> functions.
cannam@85 913 </P>
cannam@85 914 <P>
cannam@85 915 Parameters:
cannam@85 916 <PRE>
cannam@85 917 sndfile : A valid SNDFILE* pointer
cannam@85 918 cmd : SFC_UPDATE_HEADER_NOW
cannam@85 919 data : Not used (should be NULL)
cannam@85 920 datasize : SF_TRUE or SF_FALSE
cannam@85 921 </PRE>
cannam@85 922 <P>
cannam@85 923 Example:
cannam@85 924 </P>
cannam@85 925 <PRE>
cannam@85 926 /* Turn on auto header update. */
cannam@85 927 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
cannam@85 928
cannam@85 929 /* Turn off auto header update. */
cannam@85 930 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
cannam@85 931 </PRE>
cannam@85 932 <DL>
cannam@85 933 <DT>Return value:</DT>
cannam@85 934 <DD>TRUE if auto update header is now on; FALSE otherwise.
cannam@85 935 </DL>
cannam@85 936
cannam@85 937 <!-- ========================================================================= -->
cannam@85 938 <A NAME="SFC_FILE_TRUNCATE"></A>
cannam@85 939 <H2><BR><B>SFC_FILE_TRUNCATE</B></H2>
cannam@85 940 <P>
cannam@85 941 Truncate a file open for write or for read/write.
cannam@85 942 </P>
cannam@85 943 <P>
cannam@85 944 Parameters:
cannam@85 945 <PRE>
cannam@85 946 sndfile : A valid SNDFILE* pointer
cannam@85 947 cmd : SFC_FILE_TRUNCATE
cannam@85 948 data : A pointer to an sf_count_t.
cannam@85 949 datasize : sizeof (sf_count_t)
cannam@85 950 </PRE>
cannam@85 951
cannam@85 952 <P>
cannam@85 953 Truncate the file to the number of frames specified by the sf_count_t pointed
cannam@85 954 to by data.
cannam@85 955 After this command, both the read and the write pointer will be
cannam@85 956 at the new end of the file.
cannam@85 957 This command will fail (returning non-zero) if the requested truncate position
cannam@85 958 is beyond the end of the file.
cannam@85 959 </P>
cannam@85 960 <P>
cannam@85 961 Example:
cannam@85 962 </P>
cannam@85 963 <PRE>
cannam@85 964 /* Truncate the file to a length of 20 frames. */
cannam@85 965 sf_count_t frames = 20 ;
cannam@85 966 sf_command (sndfile, SFC_FILE_TRUNCATE, &amp;frames, sizeof (frames)) ;
cannam@85 967 </PRE>
cannam@85 968 <DL>
cannam@85 969 <DT>Return value:</DT>
cannam@85 970 <DD>Zero on sucess, non-zero otherwise.
cannam@85 971 </DL>
cannam@85 972
cannam@85 973 <!-- ========================================================================= -->
cannam@85 974 <A NAME="SFC_SET_RAW_START_OFFSET"></A>
cannam@85 975 <H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2>
cannam@85 976 <P>
cannam@85 977 Change the data start offset for files opened up as SF_FORMAT_RAW.
cannam@85 978 </P>
cannam@85 979 <P>
cannam@85 980 Parameters:
cannam@85 981 <PRE>
cannam@85 982 sndfile : A valid SNDFILE* pointer
cannam@85 983 cmd : SFC_SET_RAW_START_OFFSET
cannam@85 984 data : A pointer to an sf_count_t.
cannam@85 985 datasize : sizeof (sf_count_t)
cannam@85 986 </PRE>
cannam@85 987
cannam@85 988 <P>
cannam@85 989 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
cannam@85 990 given by data.
cannam@85 991 </P>
cannam@85 992 <P>
cannam@85 993 Example:
cannam@85 994 </P>
cannam@85 995 <PRE>
cannam@85 996 /* Reset the data offset to 5 bytes from the start of the file. */
cannam@85 997 sf_count_t offset = 5 ;
cannam@85 998 sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &amp;offset, sizeof (offset)) ;
cannam@85 999 </PRE>
cannam@85 1000 <DL>
cannam@85 1001 <DT>Return value:</DT>
cannam@85 1002 <DD>Zero on sucess, non-zero otherwise.
cannam@85 1003 </DL>
cannam@85 1004
cannam@85 1005 <!-- ========================================================================= -->
cannam@85 1006
cannam@85 1007 <HR>
cannam@85 1008 <P>
cannam@85 1009 The libsndfile home page is here :
cannam@85 1010 <A HREF="http://www.mega-nerd.com/libsndfile/">
cannam@85 1011 http://www.mega-nerd.com/libsndfile/</A>.
cannam@85 1012 <BR>
cannam@85 1013 Version : 1.0.25
cannam@85 1014 </P>
cannam@85 1015
cannam@85 1016 </BODY>
cannam@85 1017 </HTML>