|
|
| Line 15: |
Line 15: |
| | * [http://svn.blea.ch/thdslib/trunk/thdslib/examples/rng32Lib/ rng32Lib example] | | * [http://svn.blea.ch/thdslib/trunk/thdslib/examples/rng32Lib/ rng32Lib example] |
| | | | |
| − | ==Functions==
| + | Big help, big help. And superlative news of cruose. |
| − | The function descriptions here are given using the character/8bit versions of the functions. For the 32 bit version, please note that function names and data type names are the same, except where indicated, and prefixed with either 'rng32' for functions, 'RNG32' for macros, and 'RING32_ID' for data types. They function in an identical manner except for using unsigned long int (u32) instead of char (u8) for data.
| + | |
| − | | + | |
| − | '''rngCreate'''<br>
| + | |
| − | Creates a new ring buffer instance
| + | |
| − | * nbytes - number to bytes (or 32 bit words for thFifo32) to be allocated for this buffer. Directly represents how much data the buffer can hold.
| + | |
| − | <source lang="c">
| + | |
| − | RING_ID rngCreate(int nbytes);
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngDelete'''<br>
| + | |
| − | Deletes a ring buffer instance
| + | |
| − | * ringId - object of type RING_ID to be destroyed
| + | |
| − | <source lang="c">
| + | |
| − | void rngDelete(RING_ID ringId);
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngFlush'''<br>
| + | |
| − | Removes all content from ring buffer.
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | <source lang="c">
| + | |
| − | void rngFlush(RING_ID ringId); //empty all buffer content,
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngBufGet'''<br>
| + | |
| − | Retrieves data, if available, from ring buffer.
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | * buffer - point to buffer to contain data
| + | |
| − | * maxbytes - maximum number of bytes to be read
| + | |
| − | <source lang="c">
| + | |
| − | int rngBufGet(RING_ID rngId, char *buffer, int maxbytes); //get number of chars, retuns nbytes gotten
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngBufPut'''<br>
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | * buffer - pointer to buffer containing data to be placed into buffer
| + | |
| − | * nbytes - number of bytes to place into buffer, usually the length of buffer.
| + | |
| − | Returns the number of bytes actually written to the buffer. If buffer is full will return 0.
| + | |
| − | <source lang="c">
| + | |
| − | int rngBufPut(RING_ID rngId, char *buffer, int nbytes); //write a number of chars, returns nbytes put
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngIsEmpty'''<br>
| + | |
| − | Test if ring buffer contains data
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | Returns true if ring buffer is empty, otherwise false.
| + | |
| − | <source lang="c">
| + | |
| − | bool rngIsEmpty(RING_ID ringId); //tst if buffer is empty
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngCreate'''<br>
| + | |
| − | Test if ring buffer is at maximum capacity
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | Returns true if buffer is full, otherwise false
| + | |
| − | <source lang="c">
| + | |
| − | bool rngIsFull(RING_ID ringId); //tst if full
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngFreeBytes/rng32FreeWords'''<br>
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | Returns an integer indicating the maximum number of bytes (or 32 bit words for thFifo32) that may be placed in buffer before it is full.
| + | |
| − | <source lang="c">
| + | |
| − | int rngFreeBytes(RING_ID ringId); //how many free bytes remain?
| + | |
| − | </source>
| + | |
| − | 32bit version
| + | |
| − | <source lang="c">
| + | |
| − | int rng32FreeWords(RING_ID ringId); //how many free bytes remain?
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngNBytes/rng32NWords'''<br>
| + | |
| − | Number of bytes bytes (or 32 bit words for thFifo32) that may be gotten from the ring buffer
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | Returns number of bytes (or 32 bit words for thFifo32) that may be retrieved from buffer
| + | |
| − | <source lang="c">
| + | |
| − | int rngNBytes(RING_ID ringId);
| + | |
| − | </source>
| + | |
| − | 32bit version
| + | |
| − | <source lang="c">
| + | |
| − | int rngNWords(RING_ID ringId);
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngPutAhead'''<br>
| + | |
| − | Put a single byte into ring buffer without incrementing count. rngFreeBytes, rngIsFull, or rngIsEmpty should probably be used for most cases to first determine that placing a character into the buffer will not result in overflow.
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | * byte - single character (or 32bit word for thFifo32) to be placed into buffer
| + | |
| − | * offset - where to store the data, 0 would be at first, 1 would be the character after 0, 2 would be two characters ahead, etc etc
| + | |
| − | <source lang="c">
| + | |
| − | void rngPutAhead(RING_ID ringId, char byte, int offset); //put byte in the read buffer without incrementing counter
| + | |
| − | </source>
| + | |
| − | | + | |
| − | '''rngMoveAhead'''<br>
| + | |
| − | Used in conjunction with (usually after) rngPutAhead, will increment the number of characters (or 32bit words for thFifo32) specified.
| + | |
| − | * ringId - object of type RING_ID
| + | |
| − | * n - number of bytes (or 32bit words for thFifo32) to increment fifo counter. Usually the number of bytes placed into the buffer using rngMoveAhead.
| + | |
| − | <source lang="c">
| + | |
| − | void rngMoveAhead(RING_ID ringId, int n); //move inbuffer ahead n # of bytes (used after a PutAhead)
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Now we know who the snesbile one is here. Great post!
| + | |
| | | | |
| | ==Examples== | | ==Examples== |
An example of rng32Lib usage that caches keypresses during vblank handler may be found here:
Big help, big help. And superlative news of cruose.
Write the string into buffer and read it back out again.
ring buffers are very useful. ^^
