/*
 * Copyright (c) 1999-2000, Eric Moon.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions, and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


// RawBuffer.h
// eamoon@meadgroup.com
//
// * PURPOSE
// A basic representation of a media buffer.  RawBuffer
// instances may either allocate and maintain their own buffer or
// represent external data.
//
// * HISTORY
// e.moon 	16jun99
//		realtime allocation support
// e.moon		31mar99
//		begun
//

#ifndef __RawBuffer_H__
#define __RawBuffer_H__

#include <SupportDefs.h>

struct rtm_pool;

class RawBuffer {
public:						// ctor/dtor/accessors
	virtual ~RawBuffer();

	// allocate buffer (if frames > 0)
	// [16jun99] if pFromPool is nonzero, uses realtime allocator
	//           w/ the provided pool; otherwise uses standard
	//           new[] allocator.
	RawBuffer(
		uint32 frameSize=1,
		uint32 frames=0,
		bool circular=true,
		rtm_pool* pFromPool=0);

	// point to given data (does NOT take responsibility for
	// deleting it; use adopt() for that.)
	RawBuffer(
		void* pData,
		uint32 frameSize,
		uint32 frames,
		bool bCircular=true,
		rtm_pool* pFromPool=0);

	// generate reference to the given target buffer
	RawBuffer(const RawBuffer& clone);
	RawBuffer& operator=(const RawBuffer& clone);

	// returns pointer to start of buffer
	char* data() const;
	// returns pointer to given frame
	char* frame(uint32 frame) const;

	uint32 frameSize() const;
	uint32 frames() const;
	uint32 size() const;

	bool isCircular() const;
	bool ownsBuffer() const;

	rtm_pool* pool() const;

	// resize buffer, re-allocating if necessary to contain
	// designated number of frames
	// Does not preserve buffer contents.

	void resize(uint32 frames);

	// take ownership of buffer from target
	// (deletes current buffer data, if any owned)

	void adopt(
		void* pData,
		uint32 frameSize,
		uint32 frames,
		bool bCircular=true,
		rtm_pool* pPool=0);

	// returns false if the target doesn't own the data, but references it
	// one way or the other
	bool adopt(RawBuffer& target);

	// adopt currently ref'd data (if any; returns false if no buffer data or
	// already owned)
	bool adopt();

public:						// operations

	// fill the buffer with zeroes

	void zero();

	// raw copy to destination buffer, returning the number of
	// frames written, and adjusting both offsets accordingly.
	//
	// no frames will be written if the buffers' frame sizes
	// differ.
	//
	// rawCopyTo() will repeat the source data as many times as
	// necessary to fill the desired number of frames, but
	// will write no more than the target buffer's size.

	uint32 rawCopyTo(
		RawBuffer& target,
		uint32* pioFromFrame,
		uint32* pioTargetFrame,
		uint32 frames) const;

	// more convenient version of above if you don't care
	// how the offsets change.

	uint32 rawCopyTo(
		RawBuffer& target,
		uint32 fromFrame,
		uint32 targetFrame,
		uint32 frames) const;

protected:					// internal operations
	// free owned data, if any
	// [16jun99] uses proper rtm_free() call if needed
	void free();

protected:					// members
	void*				m_pData;
	rtm_pool*		m_pPool;
	uint32			m_frameSize;
	uint32			m_frames;
	uint32			m_allocatedSize;

	bool					m_bCircular;
	bool					m_bOwnData;
};

#endif /* __RawBuffer_H__ */