Main Page   Data Structures   File List   Data Fields   Globals   Related Pages  

mpbuf.h File Reference

This graph shows which files directly or indirectly include this file:

Included by dependency graph

Go to the source code of this file.

Defines

#define MPBUG_H
#define BUF_STOPPED   0
#define BUF_STOPPING   1
#define BUF_PLAYING   2
#define BUF_STALLED   3
#define BUF_FROMWRITEPOS   -1

Functions

long BUF_GetSize ()
 Get total size of the buffer.

long BUF_GetCount ()
 Get number of bytes in the buffer.

long BUF_GetFreeBytes ()
 Get number of free bytes in the buffer.

void BUF_GetPositions (long *playpos, long *writepos)
 Get current play and write positions.

int BUF_GetState ()
 Get current buffer state.

void BUF_SetThreshold (long threshold)
 Set buffer threshold.

void BUF_Lock (long offset, long length, char **buf1, long *len1, char **buf2, long *len2)
 Get (write only) pointers to a block of bytes in the buffer.

void BUF_Unlock (long bytesWritten)
 Unlock the buffer, after bytes have been written.

unsigned BUF_Write (char *src, unsigned length)
 Write some bytes into the buffer.

void BUF_Play ()
 Start buffered playback.

void BUF_Stop ()
 Stop buffered playback.

void BUF_Flush ()
 Play remaining bytes until the buffer is empty.

void BUF_Clear ()
 Stop playback, and discard buffer bytes.

long BUF_Init (long minsize, long maxsize)
 Initialize MPEG-Buffer.

void BUF_Done ()
 Free all resources used by the MPEG-Buffer.


Define Documentation

#define BUF_FROMWRITEPOS   -1
 

Definition at line 13 of file mpbuf.h.

Referenced by BUF_Lock(), and BUF_Write().

#define BUF_PLAYING   2
 

Definition at line 8 of file mpbuf.h.

Referenced by BUF_Play(), BUF_Stop(), and callback().

#define BUF_STALLED   3
 

Definition at line 9 of file mpbuf.h.

Referenced by BUF_Flush(), BUF_Play(), BUF_Stop(), and BUF_Unlock().

#define BUF_STOPPED   0
 

Definition at line 6 of file mpbuf.h.

Referenced by BUF_Clear(), BUF_Init(), BUF_Stop(), and callback().

#define BUF_STOPPING   1
 

Definition at line 7 of file mpbuf.h.

Referenced by BUF_Stop(), and callback().

#define MPBUG_H
 

Definition at line 2 of file mpbuf.h.


Function Documentation

void BUF_Clear  
 

Stop playback, and discard buffer bytes.

Definition at line 359 of file mpbuf.cpp.

References BUF_Stop(), BUF_STOPPED, bufCount, bufHead, and bufState.

Referenced by http_get().

void BUF_Done  
 

Free all resources used by the MPEG-Buffer.

Definition at line 413 of file mpbuf.cpp.

References BUF_Stop(), bufPtr, and bufSize.

void BUF_Flush  
 

Play remaining bytes until the buffer is empty.

Definition at line 346 of file mpbuf.cpp.

References BUF_Play(), BUF_STALLED, BUF_Stop(), bufState, and RTX_Sleep_Time().

long BUF_GetCount  
 

Get number of bytes in the buffer.

Returns:
number of bytes.

Definition at line 86 of file mpbuf.cpp.

References bufCount.

Referenced by BUF_GetFreeBytes(), and BUF_Play().

long BUF_GetFreeBytes  
 

Get number of free bytes in the buffer.

You should call this function to find out how many bytes can (at least) be written by the next BUF_Write() call.

Returns:
number of free bytes in the buffer.

Definition at line 102 of file mpbuf.cpp.

References BUF_GetCount(), and BUF_GetSize().

Referenced by BUF_Write(), and http_get().

void BUF_GetPositions long *    playpos,
long *    writepos
 

Get current play and write positions.

Note:
The write position is always some bytes ahead of the play position. (only in case of an empty buffer, the write position equals the play position)
Parameters:
playpos  pointer to variable receiving the current play position. (may be NULL)
writepos  poitner to variable receiving the current write position. (may be NULL)

Definition at line 164 of file mpbuf.cpp.

References bufCount, bufHead, and bufSize.

Referenced by BUF_Lock().

long BUF_GetSize  
 

Get total size of the buffer.

Returns:
number of allocated bytes.

Definition at line 76 of file mpbuf.cpp.

References bufSize.

Referenced by BUF_GetFreeBytes(), and http_get().

int BUF_GetState  
 

Get current buffer state.

During playback, the buffer can be in various states:

  • BUF_STOPPED Buffer playback is completely stopped.
  • BUF_STOPPING Playback is just about to stop, and is waiting for the current DMA transfer to finish.
  • BUF_PLAYING Playback is in progress.
  • BUF_STALLED The buffer is waiting for more bytes.
See also:
BUF_SetThreshold();
Returns:
current buffer state

Definition at line 125 of file mpbuf.cpp.

References bufState.

long BUF_Init long    minsize,
long    maxsize
 

Initialize MPEG-Buffer.

BUF_Init first tries to allocate maxsize bytes for its internal buffer; if there is not enough memory, the size is reduced by 16k, until a buffer could be allocated. The minimum buffer size is bounded by minsize.

Note:
if you want need a specific buffer size, set minsize = maxsize.
Parameters:
minsize  minimum buffer size to allocate.
maxsize  maximum buffer size to allocate.
Returns:
number of bytes allocated, or 0 if init failed.

Definition at line 382 of file mpbuf.cpp.

References BUF_STOPPED, bufCount, bufHead, bufPtr, bufSize, bufState, bufThreshold, and VS_FIFOSIZE.

void BUF_Lock long    offset,
long    length,
char **    buf1,
long *    len1,
char **    buf2,
long *    len2
 

Get (write only) pointers to a block of bytes in the buffer.

Because the buffer is circular, a wrap around may be needed if you want to access a block of bytes. This function calculates the correct pointers into the buffer for a given starting position and length. If you only want pointers to the first portion of the buffer, you can give NULL pointers for buf2 and len2.

Note:
Please use the returned pointers for write access only. The implementation of the buffer might change in the future, and a read may not return valid data. (i plan to use multiple small buffers instead of one big memory area for future versions)
Parameters:
offset  byte offset, may be set to BUF_FROMWRITEPOS.
length  maximum number of bytes to lock
buf1  Address of a variable that receives a pointer to the first part of the buffer
len1  Address of a variable that receives the number of bytes in the block at buf1.
buf2  Address of a variable that receives a pointer to the second part of the buffer. If this variable receives a NULL pointer, a wrap around wasn't needed.
len1  Address of a variable that receives the number of bytes in the block at buf2.

Definition at line 202 of file mpbuf.cpp.

References BUF_FROMWRITEPOS, BUF_GetPositions(), bufPtr, and bufSize.

Referenced by BUF_Play(), BUF_Write(), and http_get().

void BUF_Play  
 

Start buffered playback.

The BUF_Play() function will start playback immediately if the buffer was in the BUF_STOPPED state. If there are no bytes in the buffer, it will enter the BUF_STALLED state instead. (note that the BUF_Play() function will force playback, even if there are fewer than bufThreshold bytes in the buffer. The threshold will only be respected, if the buffer enters the BUF_STALLED state during playback.)

The actual playback is done by the VS_PlayMpegAsync function, and will play blocks of <= VS_FIFOSIZE bytes.

Definition at line 306 of file mpbuf.cpp.

References BUF_GetCount(), BUF_Lock(), BUF_PLAYING, BUF_STALLED, bufHead, bufState, callback(), VS_FIFOSIZE, VS_IsPlaying(), and VS_PlayMpegAsync().

Referenced by BUF_Flush(), BUF_Unlock(), callback(), and http_get().

void BUF_SetThreshold long    threshold
 

Set buffer threshold.

The threshold value sets the amount of bytes that have to be written into the buffer, to continue playing after a buffer stall. This is useful, if you expect an unreliable data stream, like http-connections over the internet. With a treshold value of, say half the buffer size, you can avoid excessive stuttering while recovering from a buffer stall.

Note:
the default threshold value equals VS_FIFOSIZE.
Parameters:
threshold  number of bytes needed to recover from the BUF_STALLED state.

Definition at line 146 of file mpbuf.cpp.

References bufThreshold.

Referenced by http_get().

void BUF_Stop  
 

Stop buffered playback.

If the buffer is currently in the playing state, the playback will stop directly after the current block has been played.

Definition at line 333 of file mpbuf.cpp.

References BUF_PLAYING, BUF_STALLED, BUF_STOPPED, BUF_STOPPING, and bufState.

Referenced by BUF_Clear(), BUF_Done(), and BUF_Flush().

void BUF_Unlock long    bytesWritten
 

Unlock the buffer, after bytes have been written.

You must call this function after BUF_Lock() to advance the write pointer.

Note:
If the buffer was stalled (i.e. ran out of bytes), BUF_Unlock() will only resume playback, after the buffer treshold is reached.
Parameters:
number  of bytes written into the buffer.

Definition at line 237 of file mpbuf.cpp.

References BUF_Play(), BUF_STALLED, bufCount, bufSize, bufState, and bufThreshold.

Referenced by BUF_Write(), and http_get().

unsigned BUF_Write char *    src,
unsigned    length
 

Write some bytes into the buffer.

The BUF_Write() function tries to write a maximum of length bytes at the current write position. This function is only supplied for easy (lazy) application programming, and should not be used because it copies the data. Use the BUF_Lock/BUF_Unlock functions whenever possible.

  data flow using BUF_Write
    harddisk --copy--> application --copy--> mpbuf

  data flow using BUF_Lock/BUF_Unlock
    harddisk --copy--> mpbuf
Parameters:
src  pointer to data to be copied.
length  number of bytes to be copied.
Returns:
number of actual bytes written. This may be less than length bytes, if there wasn't enough space in the buffer.

Definition at line 273 of file mpbuf.cpp.

References BUF_FROMWRITEPOS, BUF_GetFreeBytes(), BUF_Lock(), BUF_Unlock(), and src.


Generated on Sun Aug 4 21:47:40 2002 for k/os mp3v2 by doxygen1.2.16