annotate extra_rwops.h @ 513:006e3d6cd2fe

Patch to get mpglib going again, from Sam.
author Ryan C. Gordon <icculus@icculus.org>
date Fri, 12 May 2006 14:43:27 +0000
parents c7ab783f05d3
children 2df1f5c62d38
rev   line source
8
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
1 /*
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
2 * SDL_sound -- An abstract sound format decoding API.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
3 * Copyright (C) 2001 Ryan C. Gordon.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
4 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
5 * This library is free software; you can redistribute it and/or
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
6 * modify it under the terms of the GNU Lesser General Public
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
7 * License as published by the Free Software Foundation; either
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
8 * version 2.1 of the License, or (at your option) any later version.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
9 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
10 * This library is distributed in the hope that it will be useful,
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
13 * Lesser General Public License for more details.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
14 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
15 * You should have received a copy of the GNU Lesser General Public
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16 * License along with this library; if not, write to the Free Software
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
18 */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
19
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
20 /*
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
21 * Some extra RWops that are needed or are just handy to have.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
22 *
184
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING".
Ryan C. Gordon <icculus@icculus.org>
parents: 8
diff changeset
23 * Please see the file COPYING in the source's root directory.
8
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
24 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
25 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
26 */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
27
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
28 #ifndef _INCLUDE_EXTRA_RWOPS_H_
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
29 #define _INCLUDE_EXTRA_RWOPS_H_
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
30
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
31 #include "SDL.h"
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
32
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
33 #ifdef __cplusplus
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
34 extern "C" {
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
35 #endif
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
36
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
37 /*
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
38 * The Reference Counter RWops...
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
39 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
40 * This wraps another RWops with a reference counter. When you create a
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
41 * reference counter RWops, it sets a counter to one. Everytime you call
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
42 * RWops_RWRefCounter_new(), that's RWops's counter increments by one.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
43 * Everytime you call that RWops's close() method, the counter decrements
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
44 * by one. If the counter hits zero, the original RWops's close() method
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
45 * is called, and the reference counting wrapper deletes itself. The read,
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
46 * write, and seek methods just pass through to the original.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
47 *
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
48 * This is handy if you have two libraries (in the original case, SDL_sound
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
49 * and SMPEG), who both want an SDL_RWops, and both want to close it when
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
50 * they are finished. This resolves that contention. The user creates a
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
51 * RWops, passes it to SDL_sound, which wraps it in a reference counter and
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
52 * increments the number of references, and passes the wrapped RWops to
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
53 * SMPEG. SMPEG "closes" this wrapped RWops when the MP3 has finished
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
54 * playing, and SDL_sound then closes it, too. This second closing removes
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
55 * the last reference, and the RWops is smoothly destructed.
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
56 */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
57
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
58 /* Return a SDL_RWops that is a reference counting wrapper of (rw). */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
59 SDL_RWops *RWops_RWRefCounter_new(SDL_RWops *rw);
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
60
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
61 /* Increment a reference counting RWops's refcount by one. */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
62 void RWops_RWRefCounter_addRef(SDL_RWops *rw);
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
63
485
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
64
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
65 /*
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
66 * RWops pooling. This is to reduce malloc() pressure for audio that is
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
67 * placed into Sound_Samples over and over again.
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
68 */
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
69
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
70 /* Call this first. */
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
71 int RWops_pooled_init(void);
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
72
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
73 /* Call this last. */
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
74 int RWops_pooled_deinit(void);
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
75
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
76 /* Get a new RWops, allocating if needed. */
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
77 SDL_RWops *RWops_pooled_alloc(void);
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
78
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
79 /* Return a RWops to the pool for reuse. */
490
c7ab783f05d3 Patched to compile.
Ryan C. Gordon <icculus@icculus.org>
parents: 485
diff changeset
80 void RWops_pooled_free(SDL_RWops *rw);
485
137c0b00ea4c Added Sound_NewSampleFromMem(), and implementation of RWops pooling.
Ryan C. Gordon <icculus@icculus.org>
parents: 184
diff changeset
81
8
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
82 #ifdef __cplusplus
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
83 }
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
84 #endif
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
85
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
86 #endif /* !defined _INCLUDE_EXTRA_RWOPS_H_ */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
87
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
88 /* end of extra_rwops.h ... */
dca15bb29d35 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
89