1 | /* -*- mode: C; tab-width:8; c-basic-offset:8 -*- |
---|
2 | * vi:set ts=8: |
---|
3 | * |
---|
4 | * al_bpool.h |
---|
5 | * |
---|
6 | * Prototypes, macros and definitions related to the management of bpool |
---|
7 | * objects. bpool objects are objects which ease the slab allocation of |
---|
8 | * AL_buffer objects. |
---|
9 | * |
---|
10 | */ |
---|
11 | #ifndef _AL_BPOOL_H_ |
---|
12 | #define _AL_BPOOL_H_ |
---|
13 | |
---|
14 | #include "al_types.h" |
---|
15 | |
---|
16 | /* |
---|
17 | * pool structures: bpool_node and bpool_t |
---|
18 | * |
---|
19 | * These structures are used to group buffers in a growable array, so that |
---|
20 | * the relatively small allocations of AL_buffer objects can be combined into |
---|
21 | * a larger structure, in the hopes of reducing the effects of fragmentation. |
---|
22 | * |
---|
23 | * Each AL_buffer manipulated is actually a pointer to a bpool_node->data |
---|
24 | * object. The bpool->node inuse flag marks whether the AL_buffer in a bpool_node |
---|
25 | * object is currently "alloced" (in the sense that the application/library is |
---|
26 | * using it) or "dealloced". |
---|
27 | * |
---|
28 | * The bpool_t object is used to collect those variables needed to manage the |
---|
29 | * bpool_node pool, in point of fact the size and the data itself. Also, a |
---|
30 | * mapping of buffer ids (used internally and by the application) is present |
---|
31 | * to facilitate the easy conversion from buffer ids (which are in essence |
---|
32 | * arbitrary other than their requirement to be unique) and indexes into |
---|
33 | * the bpool_node pool. |
---|
34 | */ |
---|
35 | typedef struct { |
---|
36 | AL_buffer data; |
---|
37 | ALboolean inuse; |
---|
38 | } bpool_node; |
---|
39 | |
---|
40 | typedef struct { |
---|
41 | bpool_node *pool; |
---|
42 | ALuint size; |
---|
43 | ALuint *map; /* map[index] = bid */ |
---|
44 | } bpool_t; |
---|
45 | |
---|
46 | /* |
---|
47 | * buffer pool stuff |
---|
48 | * |
---|
49 | * overcomplicated method of pooling buffers to avoid memory |
---|
50 | * fragmentation. |
---|
51 | */ |
---|
52 | |
---|
53 | /* |
---|
54 | * initializes buffer pool object (bpool). |
---|
55 | */ |
---|
56 | void bpool_init( bpool_t *bpool ); |
---|
57 | |
---|
58 | /* |
---|
59 | * allocates a buffer pool node from bpool, returns index or -1 |
---|
60 | * on error. |
---|
61 | */ |
---|
62 | int bpool_alloc( bpool_t *bpool ); |
---|
63 | |
---|
64 | /* |
---|
65 | * dealloc all buffer pool nodes in a buffer pool object, using freer_func to |
---|
66 | * finalize each node. |
---|
67 | */ |
---|
68 | void bpool_free( bpool_t *bpool, void (*freer_func)(void *) ); |
---|
69 | |
---|
70 | /* |
---|
71 | * returns index of first unused buffer pool node in bpool. |
---|
72 | */ |
---|
73 | int bpool_first_free_index( bpool_t *bpool ); |
---|
74 | |
---|
75 | /* |
---|
76 | * finalizes a single buffer pool node, named by bid. Returns AL_TRUE if the |
---|
77 | * buffer pool node was valid, in use, and was finalized. Returns AL_FALSE if |
---|
78 | * the buffer pool node was invalid, not in use, or any other error occured. |
---|
79 | */ |
---|
80 | ALboolean bpool_dealloc( bpool_t *bpool, ALuint bid, |
---|
81 | void (*freer_func)(void *) ); |
---|
82 | |
---|
83 | /* |
---|
84 | * increase size of buffer pool object (bpool) until it can contain up to |
---|
85 | * newsize objects. Return AL_TRUE if resize operation was successful, |
---|
86 | * AL_FALSE otherwise. |
---|
87 | */ |
---|
88 | ALboolean bpool_resize( bpool_t *bpool, size_t newsize ); |
---|
89 | |
---|
90 | /* |
---|
91 | * retrieve a buffer pool node from a buffer pool ( bpool ), with index |
---|
92 | * bindex. Returns NULL if bindex is not a valid index into the bpool. |
---|
93 | * |
---|
94 | * NOTE: bindex is *not* a buffer name (bid). It is a value returned from |
---|
95 | * a successful call to bpool_alloc. |
---|
96 | */ |
---|
97 | AL_buffer *bpool_index( bpool_t *bpool, ALuint bindex ); |
---|
98 | |
---|
99 | /* |
---|
100 | * converts an AL_buffer name (bid) to buffer pool node index suitable |
---|
101 | * for passing to bpool_index. Returns -1 if bid does not name a buffer id |
---|
102 | * within bpool. |
---|
103 | */ |
---|
104 | int bpool_bid_to_index( bpool_t *bpool, ALuint bid ); |
---|
105 | |
---|
106 | /* |
---|
107 | * return next suitable AL_buffer name (bid) suitable for using in |
---|
108 | * al calls ( alBufferData( bid, ... ), etc ). These should be sequential |
---|
109 | * and unique. |
---|
110 | */ |
---|
111 | ALuint bpool_next_bid( void ); |
---|
112 | |
---|
113 | #endif /* AL_BPOOL_H_ */ |
---|