macosx: Update main window to use new slider
[vlc.git] / include / vlc_block.h
blob2bc230f2c7ca593e832e3400684db99c4129a7f2
1 /*****************************************************************************
2 * vlc_block.h: Data blocks management functions
3 *****************************************************************************
4 * Copyright (C) 2003 VLC authors and VideoLAN
5 * $Id$
7 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation; either version 2.1 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
24 #ifndef VLC_BLOCK_H
25 #define VLC_BLOCK_H 1
27 /**
28 * \defgroup block Data blocks
29 * \ingroup input
31 * Blocks of binary data.
33 * @ref block_t is a generic structure to represent a binary blob within VLC.
34 * The primary goal of the structure is to avoid memory copying as data is
35 * passed around. It is notably used between the \ref demux, the packetizer
36 * (if present) and the \ref decoder, and for audio, between the \ref decoder,
37 * the audio filters, and the \ref audio_output.
39 * @{
40 * \file
41 * Data block definition and functions
44 #include <sys/types.h> /* for ssize_t */
46 /****************************************************************************
47 * block:
48 ****************************************************************************
49 * - i_flags may not always be set (ie could be 0, even for a key frame
50 * it depends where you receive the buffer (before/after a packetizer
51 * and the demux/packetizer implementations.
52 * - i_dts/i_pts could be VLC_TS_INVALID, it means no pts/dts
53 * - i_length: length in microseond of the packet, can be null except in the
54 * sout where it is mandatory.
56 * - i_buffer number of valid data pointed by p_buffer
57 * you can freely decrease it but never increase it yourself
58 * (use block_Realloc)
59 * - p_buffer: pointer over datas. You should never overwrite it, you can
60 * only incremment it to skip datas, in others cases use block_Realloc
61 * (don't duplicate yourself in a bigger buffer, block_Realloc is
62 * optimised for preheader/postdatas increase)
63 ****************************************************************************/
65 /** The content doesn't follow the last block, possible some blocks in between
66 * have been lost */
67 #define BLOCK_FLAG_DISCONTINUITY 0x0001
68 /** Intra frame */
69 #define BLOCK_FLAG_TYPE_I 0x0002
70 /** Inter frame with backward reference only */
71 #define BLOCK_FLAG_TYPE_P 0x0004
72 /** Inter frame with backward and forward reference */
73 #define BLOCK_FLAG_TYPE_B 0x0008
74 /** For inter frame when you don't know the real type */
75 #define BLOCK_FLAG_TYPE_PB 0x0010
76 /** Warn that this block is a header one */
77 #define BLOCK_FLAG_HEADER 0x0020
78 /** This block contains the last part of a sequence */
79 #define BLOCK_FLAG_END_OF_SEQUENCE 0x0040
80 /** This block contains a clock reference */
81 #define BLOCK_FLAG_CLOCK 0x0080
82 /** This block is scrambled */
83 #define BLOCK_FLAG_SCRAMBLED 0x0100
84 /** This block has to be decoded but not be displayed */
85 #define BLOCK_FLAG_PREROLL 0x0200
86 /** This block is corrupted and/or there is data loss */
87 #define BLOCK_FLAG_CORRUPTED 0x0400
88 /** This block contains an interlaced picture with top field stored first */
89 #define BLOCK_FLAG_TOP_FIELD_FIRST 0x0800
90 /** This block contains an interlaced picture with bottom field stored first */
91 #define BLOCK_FLAG_BOTTOM_FIELD_FIRST 0x1000
92 /** This block contains a single field from interlaced picture. */
93 #define BLOCK_FLAG_SINGLE_FIELD 0x2000
95 /** This block contains an interlaced picture */
96 #define BLOCK_FLAG_INTERLACED_MASK \
97 (BLOCK_FLAG_TOP_FIELD_FIRST|BLOCK_FLAG_BOTTOM_FIELD_FIRST|BLOCK_FLAG_SINGLE_FIELD)
99 #define BLOCK_FLAG_TYPE_MASK \
100 (BLOCK_FLAG_TYPE_I|BLOCK_FLAG_TYPE_P|BLOCK_FLAG_TYPE_B|BLOCK_FLAG_TYPE_PB)
102 /* These are for input core private usage only */
103 #define BLOCK_FLAG_CORE_PRIVATE_MASK 0x00ff0000
104 #define BLOCK_FLAG_CORE_PRIVATE_SHIFT 16
106 /* These are for module private usage only */
107 #define BLOCK_FLAG_PRIVATE_MASK 0xff000000
108 #define BLOCK_FLAG_PRIVATE_SHIFT 24
110 typedef void (*block_free_t) (block_t *);
112 struct block_t
114 block_t *p_next;
116 uint8_t *p_buffer; /**< Payload start */
117 size_t i_buffer; /**< Payload length */
118 uint8_t *p_start; /**< Buffer start */
119 size_t i_size; /**< Buffer total size */
121 uint32_t i_flags;
122 unsigned i_nb_samples; /* Used for audio */
124 mtime_t i_pts;
125 mtime_t i_dts;
126 mtime_t i_length;
128 /* Rudimentary support for overloading block (de)allocation. */
129 block_free_t pf_release;
132 VLC_API void block_Init( block_t *, void *, size_t );
135 * Allocates a block.
137 * Creates a new block with the requested size.
138 * The block must be released with block_Release().
140 * @param size size in bytes (possibly zero)
141 * @return the created block, or NULL on memory error.
143 VLC_API block_t *block_Alloc(size_t size) VLC_USED VLC_MALLOC;
145 VLC_API block_t *block_TryRealloc(block_t *, ssize_t pre, size_t body) VLC_USED;
148 * Reallocates a block.
150 * This function expands, shrinks or moves a data block.
151 * In many cases, this function can return without any memory allocation by
152 * reusing spare buffer space. Otherwise, a new block is created and data is
153 * copied.
155 * @param pre count of bytes to prepend if positive,
156 * count of leading bytes to discard if negative
157 * @param body new bytes size of the block
159 * @return the reallocated block on succes, NULL on error.
161 * @note Skipping leading bytes can be achieved directly by substracting from
162 * block_t.i_buffer and adding block_t.p_buffer.
163 * @note Discard trailing bytes can be achieved directly by substracting from
164 * block_t.i_buffer.
165 * @note On error, the block is discarded.
166 * To avoid that, use block_TryRealloc() instead.
168 VLC_API block_t *block_Realloc(block_t *, ssize_t pre, size_t body) VLC_USED;
171 * Releases a block.
173 * This function works for any @ref block_t block, regardless of the way it was
174 * allocated.
176 * @note
177 * If the block is in a chain, this function does <b>not</b> release any
178 * subsequent block in the chain. Use block_ChainRelease() for that purpose.
180 * @param block block to release (cannot be NULL)
182 static inline void block_Release(block_t *block)
184 block->pf_release(block);
187 static inline void block_CopyProperties( block_t *dst, block_t *src )
189 dst->i_flags = src->i_flags;
190 dst->i_nb_samples = src->i_nb_samples;
191 dst->i_dts = src->i_dts;
192 dst->i_pts = src->i_pts;
193 dst->i_length = src->i_length;
197 * Duplicates a block.
199 * Creates a writeable duplicate of a block.
201 * @return the duplicate on success, NULL on error.
203 VLC_USED
204 static inline block_t *block_Duplicate( block_t *p_block )
206 block_t *p_dup = block_Alloc( p_block->i_buffer );
207 if( p_dup == NULL )
208 return NULL;
210 block_CopyProperties( p_dup, p_block );
211 memcpy( p_dup->p_buffer, p_block->p_buffer, p_block->i_buffer );
213 return p_dup;
217 * Wraps heap in a block.
219 * Creates a @ref block_t out of an existing heap allocation.
220 * This is provided by LibVLC so that manually heap-allocated blocks can safely
221 * be deallocated even after the origin plugin has been unloaded from memory.
223 * When block_Release() is called, VLC will free() the specified pointer.
225 * @param addr base address of the heap allocation (will be free()'d)
226 * @param length bytes length of the heap allocation
227 * @return NULL in case of error (ptr free()'d in that case), or a valid
228 * block_t pointer.
230 VLC_API block_t *block_heap_Alloc(void *, size_t) VLC_USED VLC_MALLOC;
233 * Wraps a memory mapping in a block
235 * Creates a @ref block_t from a virtual address memory mapping (mmap).
236 * This is provided by LibVLC so that mmap blocks can safely be deallocated
237 * even after the allocating plugin has been unloaded from memory.
239 * @param addr base address of the mapping (as returned by mmap)
240 * @param length length (bytes) of the mapping (as passed to mmap)
241 * @return NULL if addr is MAP_FAILED, or an error occurred (in the later
242 * case, munmap(addr, length) is invoked before returning).
244 VLC_API block_t *block_mmap_Alloc(void *addr, size_t length) VLC_USED VLC_MALLOC;
247 * Wraps a System V memory segment in a block
249 * Creates a @ref block_t from a System V shared memory segment (shmget()).
250 * This is provided by LibVLC so that segments can safely be deallocated
251 * even after the allocating plugin has been unloaded from memory.
253 * @param addr base address of the segment (as returned by shmat())
254 * @param length length (bytes) of the segment (as passed to shmget())
255 * @return NULL if an error occurred (in that case, shmdt(addr) is invoked
256 * before returning NULL).
258 VLC_API block_t * block_shm_Alloc(void *addr, size_t length) VLC_USED VLC_MALLOC;
261 * Maps a file handle in memory.
263 * Loads a file into a block of memory through a file descriptor.
264 * If possible a private file mapping is created. Otherwise, the file is read
265 * normally. This function is a cancellation point.
267 * @note On 32-bits platforms,
268 * this function will not work for very large files,
269 * due to memory space constraints.
271 * @param fd file descriptor to load from
272 * @param write If true, request a read/write private mapping.
273 * If false, request a read-only potentially shared mapping.
275 * @return a new block with the file content at p_buffer, and file length at
276 * i_buffer (release it with block_Release()), or NULL upon error (see errno).
278 VLC_API block_t *block_File(int fd, bool write) VLC_USED VLC_MALLOC;
281 * Maps a file in memory.
283 * Loads a file into a block of memory from a path to the file.
284 * See also block_File().
286 * @param write If true, request a read/write private mapping.
287 * If false, request a read-only potentially shared mapping.
289 VLC_API block_t *block_FilePath(const char *, bool write) VLC_USED VLC_MALLOC;
291 static inline void block_Cleanup (void *block)
293 block_Release ((block_t *)block);
295 #define block_cleanup_push( block ) vlc_cleanup_push (block_Cleanup, block)
298 * \defgroup block_fifo Block chain
299 * @{
302 /****************************************************************************
303 * Chains of blocks functions helper
304 ****************************************************************************
305 * - block_ChainAppend : append a block to the last block of a chain. Try to
306 * avoid using with a lot of data as it's really slow, prefer
307 * block_ChainLastAppend, p_block can be NULL
308 * - block_ChainLastAppend : use a pointer over a pointer to the next blocks,
309 * and update it.
310 * - block_ChainRelease : release a chain of block
311 * - block_ChainExtract : extract data from a chain, return real bytes counts
312 * - block_ChainGather : gather a chain, free it and return one block.
313 ****************************************************************************/
314 static inline void block_ChainAppend( block_t **pp_list, block_t *p_block )
316 if( *pp_list == NULL )
318 *pp_list = p_block;
320 else
322 block_t *p = *pp_list;
324 while( p->p_next ) p = p->p_next;
325 p->p_next = p_block;
329 static inline void block_ChainLastAppend( block_t ***ppp_last, block_t *p_block )
331 block_t *p_last = p_block;
333 **ppp_last = p_block;
335 while( p_last->p_next ) p_last = p_last->p_next;
336 *ppp_last = &p_last->p_next;
339 static inline void block_ChainRelease( block_t *p_block )
341 while( p_block )
343 block_t *p_next = p_block->p_next;
344 block_Release( p_block );
345 p_block = p_next;
349 static size_t block_ChainExtract( block_t *p_list, void *p_data, size_t i_max )
351 size_t i_total = 0;
352 uint8_t *p = (uint8_t*)p_data;
354 while( p_list && i_max )
356 size_t i_copy = __MIN( i_max, p_list->i_buffer );
357 memcpy( p, p_list->p_buffer, i_copy );
358 i_max -= i_copy;
359 i_total += i_copy;
360 p += i_copy;
362 p_list = p_list->p_next;
364 return i_total;
367 static inline void block_ChainProperties( block_t *p_list, int *pi_count, size_t *pi_size, mtime_t *pi_length )
369 size_t i_size = 0;
370 mtime_t i_length = 0;
371 int i_count = 0;
373 while( p_list )
375 i_size += p_list->i_buffer;
376 i_length += p_list->i_length;
377 i_count++;
379 p_list = p_list->p_next;
382 if( pi_size )
383 *pi_size = i_size;
384 if( pi_length )
385 *pi_length = i_length;
386 if( pi_count )
387 *pi_count = i_count;
390 static inline block_t *block_ChainGather( block_t *p_list )
392 size_t i_total = 0;
393 mtime_t i_length = 0;
394 block_t *g;
396 if( p_list->p_next == NULL )
397 return p_list; /* Already gathered */
399 block_ChainProperties( p_list, NULL, &i_total, &i_length );
401 g = block_Alloc( i_total );
402 if( !g )
403 return NULL;
404 block_ChainExtract( p_list, g->p_buffer, g->i_buffer );
406 g->i_flags = p_list->i_flags;
407 g->i_pts = p_list->i_pts;
408 g->i_dts = p_list->i_dts;
409 g->i_length = i_length;
411 /* free p_list */
412 block_ChainRelease( p_list );
413 return g;
417 * @}
418 * \defgroup fifo Block FIFO
419 * Thread-safe block queue functions
420 * @{
424 * Creates a thread-safe FIFO queue of blocks.
426 * See also block_FifoPut() and block_FifoGet().
427 * The created queue must be released with block_FifoRelease().
429 * @return the FIFO or NULL on memory error
431 VLC_API block_fifo_t *block_FifoNew(void) VLC_USED VLC_MALLOC;
434 * Destroys a FIFO created by block_FifoNew().
436 * @note Any queued blocks are also destroyed.
437 * @warning No other threads may be using the FIFO when this function is
438 * called. Otherwise, undefined behaviour will occur.
440 VLC_API void block_FifoRelease(block_fifo_t *);
443 * Clears all blocks in a FIFO.
445 VLC_API void block_FifoEmpty(block_fifo_t *);
448 * Immediately queue one block at the end of a FIFO.
450 * @param fifo queue
451 * @param block head of a block list to queue (may be NULL)
453 VLC_API void block_FifoPut(block_fifo_t *fifo, block_t *block);
456 * Dequeue the first block from the FIFO. If necessary, wait until there is
457 * one block in the queue. This function is (always) cancellation point.
459 * @return a valid block
461 VLC_API block_t *block_FifoGet(block_fifo_t *) VLC_USED;
464 * Peeks the first block in the FIFO.
466 * @warning This function leaves the block in the FIFO.
467 * You need to protect against concurrent threads who could dequeue the block.
468 * Preferably, there should be only one thread reading from the FIFO.
470 * @warning This function is undefined if the FIFO is empty.
472 * @return a valid block.
474 VLC_API block_t *block_FifoShow(block_fifo_t *);
476 size_t block_FifoSize(block_fifo_t *) VLC_USED VLC_DEPRECATED;
477 VLC_API size_t block_FifoCount(block_fifo_t *) VLC_USED VLC_DEPRECATED;
479 typedef struct block_fifo_t vlc_fifo_t;
482 * Locks a block FIFO.
484 * No more than one thread can lock the FIFO at any given
485 * time, and no other thread can modify the FIFO while it is locked.
486 * vlc_fifo_Unlock() releases the lock.
488 * @note If the FIFO is already locked by another thread, this function waits.
489 * This function is not a cancellation point.
491 * @warning Recursively locking a single FIFO is undefined. Locking more than
492 * one FIFO at a time may lead to lock inversion; mind the locking order.
494 VLC_API void vlc_fifo_Lock(vlc_fifo_t *);
497 * Unlocks a block FIFO.
499 * The calling thread must have locked the FIFO previously with
500 * vlc_fifo_Lock(). Otherwise, the behaviour is undefined.
502 * @note This function is not a cancellation point.
504 VLC_API void vlc_fifo_Unlock(vlc_fifo_t *);
507 * Wakes up one thread waiting on the FIFO, if any.
509 * @note This function is not a cancellation point.
511 * @warning For race-free operations, the FIFO should be locked by the calling
512 * thread. The function can be called on a unlocked FIFO however.
514 VLC_API void vlc_fifo_Signal(vlc_fifo_t *);
517 * Waits on the FIFO.
519 * Atomically unlocks the FIFO and waits until one thread signals the FIFO,
520 * then locks the FIFO again. A signal can be sent by queueing a block to the
521 * previously empty FIFO or by calling vlc_fifo_Signal() directly.
522 * This function may also return spuriously at any moment.
524 * @note This function is a cancellation point. In case of cancellation, the
525 * the FIFO will be locked before cancellation cleanup handlers are processed.
527 VLC_API void vlc_fifo_Wait(vlc_fifo_t *);
529 VLC_API void vlc_fifo_WaitCond(vlc_fifo_t *, vlc_cond_t *);
532 * Timed variant of vlc_fifo_WaitCond().
534 * Atomically unlocks the FIFO and waits until one thread signals the FIFO up
535 * to a certain date, then locks the FIFO again. See vlc_fifo_Wait().
537 int vlc_fifo_TimedWaitCond(vlc_fifo_t *, vlc_cond_t *, mtime_t);
540 * Queues a linked-list of blocks into a locked FIFO.
542 * @param block the head of the list of blocks
543 * (if NULL, this function has no effects)
545 * @note This function is not a cancellation point.
547 * @warning The FIFO must be locked by the calling thread using
548 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
550 VLC_API void vlc_fifo_QueueUnlocked(vlc_fifo_t *, block_t *);
553 * Dequeues the first block from a locked FIFO, if any.
555 * @note This function is not a cancellation point.
557 * @warning The FIFO must be locked by the calling thread using
558 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
560 * @return the first block in the FIFO or NULL if the FIFO is empty
562 VLC_API block_t *vlc_fifo_DequeueUnlocked(vlc_fifo_t *) VLC_USED;
565 * Dequeues the all blocks from a locked FIFO.
567 * This is equivalent to calling vlc_fifo_DequeueUnlocked() repeatedly until
568 * the FIFO is emptied, but this function is much faster.
570 * @note This function is not a cancellation point.
572 * @warning The FIFO must be locked by the calling thread using
573 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
575 * @return a linked-list of all blocks in the FIFO (possibly NULL)
577 VLC_API block_t *vlc_fifo_DequeueAllUnlocked(vlc_fifo_t *) VLC_USED;
580 * Counts blocks in a FIFO.
582 * Checks how many blocks are queued in a locked FIFO.
584 * @note This function is not cancellation point.
586 * @warning The FIFO must be locked by the calling thread using
587 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
589 * @return the number of blocks in the FIFO (zero if it is empty)
591 VLC_API size_t vlc_fifo_GetCount(const vlc_fifo_t *) VLC_USED;
594 * Counts bytes in a FIFO.
596 * Checks how many bytes are queued in a locked FIFO.
598 * @note This function is not cancellation point.
600 * @warning The FIFO must be locked by the calling thread using
601 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
603 * @return the total number of bytes
605 * @note Zero bytes does not necessarily mean that the FIFO is empty since
606 * a block could contain zero bytes. Use vlc_fifo_GetCount() to determine if
607 * a FIFO is empty.
609 VLC_API size_t vlc_fifo_GetBytes(const vlc_fifo_t *) VLC_USED;
611 VLC_USED static inline bool vlc_fifo_IsEmpty(const vlc_fifo_t *fifo)
613 return vlc_fifo_GetCount(fifo) == 0;
616 static inline void vlc_fifo_Cleanup(void *fifo)
618 vlc_fifo_Unlock((vlc_fifo_t *)fifo);
620 #define vlc_fifo_CleanupPush(fifo) vlc_cleanup_push(vlc_fifo_Cleanup, fifo)
622 /** @} */
624 /** @} */
626 #endif /* VLC_BLOCK_H */