blt.h

BlackFin处理器视频演示代码

/**
 * @file blt.h
 * @author Zlatan Stanojevic
 */
 


#ifndef VIDEO_BUFFER_H
#define VIDEO_BUFFER_H

#include <services/services.h>


/// Values returned by \ref blt and \ref blt_init
typedef enum
{
	BLT_OK = 0,   ///< function exited successfully
	BLT_DIM,       ///< wrong surface dimensions
	BLT_ADI_DMA_ERROR, ///< an adi_dma function call failed
} BLT_RESULT;


typedef struct
{
     void *start_addr;                 ///< start address of buffer
     unsigned short width;             ///< surface width
     unsigned short height;            ///< surface height
     unsigned long offset;             ///< address ofset of first visible pixel
     unsigned short pixel_stride;      ///< address diffecence between neighbouring pixels
     unsigned short line_stride;       ///< address difference between two consecutive line starts
     unsigned long field_stride;       ///< address difference between the start if field 1 and 2
     unsigned short interlaced : 1;    ///< interlaces surface
} BLTBufferDesc;


/**
 * @brief Generates descriptor for a plain linear surface.
 * 
 * @param addr   Start address of buffer containing the entire image information.
 * @param width  Image width.
 * @param heigth Image height.
 * 
 * @return The buffer descriptor.
 */
static inline BLTBufferDesc blt_makeLinearSurface( void *addr, unsigned short width, unsigned short height )
{
	return (BLTBufferDesc){ addr, width, height, 0, 4, width * 2, 0, 0 };
}


/**
 * @brief Generates descriptor for an interlaced surface.
 * 
 * Same as @ref makeLinearSurface only that the upper half of the image is interpreted as fiels one
 * and the lower half as field two.
 * 
 * @param addr   Start address of buffer containing the entire image information.
 * @param width  Image width.
 * @param heigth Image height.
 * 
 * @return The buffer descriptor.
 */
static inline BLTBufferDesc blt_makeInterlacedSurface( void *addr, unsigned short width, unsigned short height )
{
	return (BLTBufferDesc){ addr, width, height, 0, 4, width * 2, width * height, 1 };
}


/**
 * @brief Generates descriptor for a plain single coloured surface
 * 
 * Using this function a surface of arbitrary size can be created where each pixel hast the same colour.
 * 
 * @return The buffer description
 * @param sample   Colour sample to paint the surface with.
 * @param width  Image width.
 * @param heigth Image height.
 * 
 * @return The buffer descriptor.
 */
static inline BLTBufferDesc blt_makeFilledSurface( unsigned long *sample, unsigned short width, unsigned short height )
{
	return (BLTBufferDesc){ sample, width, height, 0, 0, 0, 0 };
}


/**
 * @brief Reduces image's width or height.
 * 
 * Use this function to effectively divide the width or height of an image by a natural number. This works
 * disregarding the buffer's geometry or interlacing.
 * 
 * @note The buffer's memory size will @b not change. The image will only @a appear scaled.
 * 
 * @param desc       The buffer descriptor to be modified.
 * @param div_width  Value by which the width is divided.
 * @param div_height Value by which the height is divided.
 * 
 * @return The new buffer descriptor.
 */
static inline BLTBufferDesc blt_shrink( BLTBufferDesc desc, unsigned short div_width, unsigned short div_height )
{
	desc.width /= div_width;
	desc.height /= div_height;
	desc.pixel_stride *= div_width;
	desc.line_stride *= div_height;
	return desc;
}


/**
 * @brief Performs a 'blit' (Block transfer) between two buffers.
 * 
 * This is perhaps the most important video buffer function. It transfers a rectangle of arbitrary
 * size and position from one buffer to another. The function takes a free MDMA channel of the 
 * specified DMA engine and enqueues the actual memory transfer as a DMA descriptor list. If both
 * MDMA channels are in use the function will wait until at least one of them is available again.
 * 
 * Interlaced buffers are supported, but special care has to be taken regarding position and size 
 * parameters when using interlaced buffers: i.e. all dimension parameters should be divisible byt two.
 * 
 * The blit function does not apply any tranformation (e.g. scaling) to the transferred region. For
 * Image scaling refer to the @ref shrink function.
 * 
 * @param stream_id      Selects which MDMA channel to use for transfer.
 * @param src            Pointer that yields to the source buffer's descriptor
 * @param dest           Pointer that yields to the destination buffer's descriptor
 * @param src_x          X coordinate of the transfer rectangle's upper left corner in
                         source buffer space
 * @param src_y          Y coordinate of the transfer rectangle's upper left corner in
                         source buffer space
 * @param dest_x         X coordinate of the transfer rectangle's upper left corner in
                         destination buffer space
 * @param dest_y         Y coordinate of the transfer rectangle's upper left corner in
                         destination buffer space
 * @param width          Width of the transferred rectangular region. This value must be
                         @b divisible @b by @b two.
 * @param height         Height of the transferred rectangular region. 
 * @return @ref BLT_OK, @ref BLT_DIM, @ref BLT_ADI_DMA_ERROR
 */
BLT_RESULT blt( ADI_DMA_STREAM_ID stream_id, BLTBufferDesc *src, BLTBufferDesc *dest, 
			 unsigned short src_x, unsigned short src_y, unsigned short dest_x, 
			 unsigned short dest_y, unsigned short width, unsigned short height );

/**
 * @brief Initializes an internal adi_dma instance.
 * @return @ref BLT_OK
 */
BLT_RESULT blt_init(void);



#endif