vlc_picture_pool.h File Reference

Include dependency graph for vlc_picture_pool.h:

Go to the source code of this file.

Data Structures
struct	picture_pool_configuration_t
	Picture pool configuration. More...

Typedefs
typedef struct picture_pool_t	picture_pool_t
	Picture pool handle. More...

Functions
picture_pool_t *	picture_pool_NewExtended (const picture_pool_configuration_t *)
	Creates a pool of preallocated pictures. More...
picture_pool_t *	picture_pool_New (unsigned count, picture_t *const *tab)
	Creates a picture pool with pictures in a given array. More...
picture_pool_t *	picture_pool_NewFromFormat (const video_format_t *fmt, unsigned count)
	Allocates pictures from the heap and creates a picture pool with them. More...
void	picture_pool_Release (picture_pool_t *)
	Releases a pool created by picture_pool_NewExtended(), picture_pool_New() or picture_pool_NewFromFormat(). More...
picture_t *	picture_pool_Get (picture_pool_t *)
	Obtains a picture from a pool if any is immediately available. More...
picture_t *	picture_pool_Wait (picture_pool_t *)
	Obtains a picture from a pool. More...
void	picture_pool_Enum (picture_pool_t *, void(*cb)(void *, picture_t *), void *data)
	Enumerates all pictures in a pool, both free and allocated. More...
void	picture_pool_Cancel (picture_pool_t *, bool canceled)
	Cancel the picture pool. More...
bool	picture_pool_OwnsPic (picture_pool_t *, picture_t *)
	Test if a picture belongs to the picture pool. More...
picture_pool_t *	picture_pool_Reserve (picture_pool_t *, unsigned count)
	Reserves pictures from a pool and creates a new pool with those. More...
unsigned	picture_pool_GetSize (const picture_pool_t *)

Detailed Description

This file defines picture pool structures and functions in vlc

Typedef Documentation

picture_pool_t

typedef struct picture_pool_t picture_pool_t

Picture pool handle.

Function Documentation

picture_pool_Cancel()

void picture_pool_Cancel	(	picture_pool_t *	,
		bool	canceled
	)

Cancel the picture pool.

It won't return any pictures via picture_pool_Get or picture_pool_Wait if canceled is true. This function will also unblock picture_pool_Wait. picture_pool_Reset will also reset the cancel state to false.

References picture_pool_t::canceled, picture_pool_t::lock, picture_pool_t::refs, vlc_cond_broadcast(), vlc_mutex_lock(), vlc_mutex_unlock(), and picture_pool_t::wait.

picture_pool_Enum()

void picture_pool_Enum	(	picture_pool_t *	,
		void(*)(void *, picture_t *)	cb,
		void *	data
	)

Enumerates all pictures in a pool, both free and allocated.

Parameters

cb	callback to invoke once for each picture
data	opaque data parameter for the callback (first argument)

Note

Allocated pictures may be accessed asynchronously by other threads. Therefore, only read-only picture parameters can be read by the callback, typically picture_t.p_sys. Provided those rules are respected, the function is thread-safe.

References picture_pool_t::picture, and picture_pool_t::picture_count.

picture_pool_Get()

picture_t* picture_pool_Get

(

picture_pool_t *

)

Obtains a picture from a pool if any is immediately available.

The picture must be released with picture_Release().

Returns

a picture, or NULL if all pictures in the pool are allocated

Note

This function is thread-safe.

< No error

References picture_pool_t::available, picture_pool_t::canceled, ffsll(), fnsll(), picture_pool_t::lock, picture_t::p_next, picture_pool_t::pic_lock, picture_pool_t::picture, picture_pool_ClonePicture(), picture_pool_t::refs, vlc_mutex_lock(), vlc_mutex_unlock(), and VLC_SUCCESS.

Referenced by picture_pool_Reserve(), and VideoBufferNew().

picture_pool_GetSize()

unsigned picture_pool_GetSize

(

const picture_pool_t *

)

Returns

the total number of pictures in the given pool

Note

This function is thread-safe.

References picture_pool_t::picture_count.

picture_pool_New()

picture_pool_t* picture_pool_New	(	unsigned	count,
		picture_t *const *	tab
	)

Creates a picture pool with pictures in a given array.

This is a convenience wrapper for picture_pool_NewExtended() without the lock and unlock callbacks.

Parameters

count	number of pictures in the array
tab	array of pictures

Returns

a pointer to the new pool on success, or NULL on error (pictures are not released on error)

References count, picture_pool_configuration_t::picture_count, and picture_pool_NewExtended().

Referenced by picture_pool_NewFromFormat(), and picture_pool_Reserve().

picture_pool_NewExtended()

picture_pool_t* picture_pool_NewExtended

(

const picture_pool_configuration_t *

)

Creates a pool of preallocated pictures.

Free pictures can be allocated from the pool, and are returned to the pool when they are no longer referenced.

This avoids allocating and deallocationg pictures repeatedly, and ensures that memory consumption remains within limits.

To obtain a picture from the pool, use picture_pool_Get(). To increase and decrease the reference count, use picture_Hold() and picture_Release() respectively.

If defined, picture_pool_configuration_t::lock will be called before a picture is used, and picture_pool_configuration_t::unlock will be called as soon as a picture is returned to the pool. Those callbacks can modify picture_t::p and access picture_t::p_sys.

Returns

A pointer to the new pool on success, or NULL on error (pictures are not released on error).

References aligned_alloc(), picture_pool_t::available, picture_pool_t::canceled, picture_pool_t::lock, picture_pool_configuration_t::lock, picture_pool_t::pic_lock, picture_pool_t::pic_unlock, picture_pool_configuration_t::picture, picture_pool_t::picture, picture_pool_configuration_t::picture_count, picture_pool_t::picture_count, POOL_MAX, picture_pool_t::refs, unlikely, picture_pool_configuration_t::unlock, vlc_cond_init(), vlc_mutex_init(), and picture_pool_t::wait.

Referenced by picture_pool_New().

picture_pool_NewFromFormat()

picture_pool_t* picture_pool_NewFromFormat	(	const video_format_t *	fmt,
		unsigned	count
	)

Allocates pictures from the heap and creates a picture pool with them.

This is a convenience wrapper for picture_NewFromFormat() and picture_pool_New().

Parameters

fmt	video format of pictures to allocate from the heap
count	number of pictures to allocate

Returns

a pointer to the new pool on success, NULL on error

References count, picture_NewFromFormat(), picture_pool_New(), and picture_Release().

picture_pool_OwnsPic()

bool picture_pool_OwnsPic	(	picture_pool_t *	,
		picture_t *
	)

Test if a picture belongs to the picture pool.

FIXME: remove this function when the vout_PutPicture() hack is fixed.

References picture_priv_t::destroy, picture_priv_t::gc, picture_priv_t::opaque, picture_pool_ReleasePicture(), and POOL_MAX.

Referenced by vout_PutPicture().

picture_pool_Release()

void picture_pool_Release

(

picture_pool_t *

)

Releases a pool created by picture_pool_NewExtended(), picture_pool_New() or picture_pool_NewFromFormat().

Note

If there are no pending references to the pooled pictures, and the picture_resource_t.pf_destroy callback was not NULL, it will be invoked. Otherwise the default callback will be used.

Warning

If there are pending references (a.k.a. late pictures), the pictures will remain valid until the all pending references are dropped by picture_Release().

References picture_pool_t::picture, picture_pool_t::picture_count, picture_pool_Destroy(), and picture_Release().

picture_pool_Reserve()

picture_pool_t* picture_pool_Reserve	(	picture_pool_t *	,
		unsigned	count
	)

Reserves pictures from a pool and creates a new pool with those.

When the new pool is released, pictures are returned to the master pool. If the master pool was already released, pictures will be destroyed.

Parameters

count

number of picture to reserve

Returns

the new pool, or NULL if there were not enough pictures available or on error

Note

This function is thread-safe (but it might return NULL if other threads have already allocated too many pictures).

References count, picture_pool_Get(), picture_pool_New(), and picture_Release().

picture_pool_Wait()

picture_t* picture_pool_Wait

(

picture_pool_t *

)

Obtains a picture from a pool.

The picture must be released with picture_Release().

Returns

a picture or NULL on memory error

Note

This function is thread-safe.

< No error

References picture_pool_t::available, picture_pool_t::canceled, ffsll(), picture_pool_t::lock, picture_t::p_next, picture_pool_t::pic_lock, picture_pool_t::picture, picture_pool_ClonePicture(), picture_pool_t::refs, vlc_cond_signal(), vlc_cond_wait(), vlc_mutex_lock(), vlc_mutex_unlock(), VLC_SUCCESS, and picture_pool_t::wait.

Referenced by vout_GetPicture().