1/*
2 * Copyright (c) 1999-2000, Eric Moon.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions, and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 *    notice, this list of conditions, and the following disclaimer in the
14 *    documentation and/or other materials provided with the distribution.
15 *
16 * 3. The name of the author may not be used to endorse or promote products
17 *    derived from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
27 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31
32// RawBuffer.h
33// eamoon@meadgroup.com
34//
35// * PURPOSE
36// A basic representation of a media buffer.  RawBuffer
37// instances may either allocate and maintain their own buffer or
38// represent external data.
39//
40// * HISTORY
41// e.moon 	16jun99
42//		realtime allocation support
43// e.moon		31mar99
44//		begun
45//
46
47#ifndef __RawBuffer_H__
48#define __RawBuffer_H__
49
50#include <SupportDefs.h>
51
52struct rtm_pool;
53
54class RawBuffer {
55public:						// ctor/dtor/accessors
56	virtual ~RawBuffer();
57
58	// allocate buffer (if frames > 0)
59	// [16jun99] if pFromPool is nonzero, uses realtime allocator
60	//           w/ the provided pool; otherwise uses standard
61	//           new[] allocator.
62	RawBuffer(
63		uint32 frameSize=1,
64		uint32 frames=0,
65		bool circular=true,
66		rtm_pool* pFromPool=0);
67
68	// point to given data (does NOT take responsibility for
69	// deleting it; use adopt() for that.)
70	RawBuffer(
71		void* pData,
72		uint32 frameSize,
73		uint32 frames,
74		bool bCircular=true,
75		rtm_pool* pFromPool=0);
76
77	// generate reference to the given target buffer
78	RawBuffer(const RawBuffer& clone);
79	RawBuffer& operator=(const RawBuffer& clone);
80
81	// returns pointer to start of buffer
82	char* data() const;
83	// returns pointer to given frame
84	char* frame(uint32 frame) const;
85
86	uint32 frameSize() const;
87	uint32 frames() const;
88	uint32 size() const;
89
90	bool isCircular() const;
91	bool ownsBuffer() const;
92
93	rtm_pool* pool() const;
94
95	// resize buffer, re-allocating if necessary to contain
96	// designated number of frames
97	// Does not preserve buffer contents.
98
99	void resize(uint32 frames);
100
101	// take ownership of buffer from target
102	// (deletes current buffer data, if any owned)
103
104	void adopt(
105		void* pData,
106		uint32 frameSize,
107		uint32 frames,
108		bool bCircular=true,
109		rtm_pool* pPool=0);
110
111	// returns false if the target doesn't own the data, but references it
112	// one way or the other
113	bool adopt(RawBuffer& target);
114
115	// adopt currently ref'd data (if any; returns false if no buffer data or
116	// already owned)
117	bool adopt();
118
119public:						// operations
120
121	// fill the buffer with zeroes
122
123	void zero();
124
125	// raw copy to destination buffer, returning the number of
126	// frames written, and adjusting both offsets accordingly.
127	//
128	// no frames will be written if the buffers' frame sizes
129	// differ.
130	//
131	// rawCopyTo() will repeat the source data as many times as
132	// necessary to fill the desired number of frames, but
133	// will write no more than the target buffer's size.
134
135	uint32 rawCopyTo(
136		RawBuffer& target,
137		uint32* pioFromFrame,
138		uint32* pioTargetFrame,
139		uint32 frames) const;
140
141	// more convenient version of above if you don't care
142	// how the offsets change.
143
144	uint32 rawCopyTo(
145		RawBuffer& target,
146		uint32 fromFrame,
147		uint32 targetFrame,
148		uint32 frames) const;
149
150protected:					// internal operations
151	// free owned data, if any
152	// [16jun99] uses proper rtm_free() call if needed
153	void free();
154
155protected:					// members
156	void*				m_pData;
157	rtm_pool*		m_pPool;
158	uint32			m_frameSize;
159	uint32			m_frames;
160	uint32			m_allocatedSize;
161
162	bool					m_bCircular;
163	bool					m_bOwnData;
164};
165
166#endif /* __RawBuffer_H__ */
167