Subversion Repositories shark

Guida all'uso del driver BTTV per S.Ha.R.K
Giacomo Guidi <giacomo@gandalf.sssup.it>

DIRECTORY DEL DRIVER: shark/drivers/bttv/
SIMBOLO NEL MAKEFILE PER INSERIRE LA LIBRERIA: __BTTV__

Il nuovo driver per Frame Grabbers e' preso al 90% dall'analogo
driver linux e supporta buona parte delle schede dotate di BT848
in commercio.

E' stato integrato anche un supporto al bus I2C necessario
per accedere ai sotto-sistemi interni al Frame Grabber, 
come chip audio o sintonizzatori televisivi.

Per utilizzare questo driver si puo' passare dai comandi base
del driver BTTV, definiti dentro bttv-driver.c oppure usare una
veloce interfaccia (fg.c) che ho creato per ridurre al minimo le 
operazioni di inizializzazione e uso della periferica.

-------------------------------------------------------------------------------
Header e funzioni per l'uso semplificato
-------------------------------------------------------------------------------

//Header delle funzioni per l'uso facilitato del Frame Grabber
#include <drivers/fg.h> 

//Header per le strutture e funzioni a basso livello del BTTV
#include <driver/bttv.h>

//Istruzione di inizializzazione semplificata
FG_init(period,wcet,width,height,color,channel);

---
period: periodo del grabbing, ovvero quanti microsecondi passano
        fra ogni campionamento dell'immagine

wcet:   durata massima del task di grabbing. Definisce quanto
        deve durare al massimo il campionamento + l'elaborazione
        dell'immagine.

width:  larghezza finestra di campionamento

height: altezza finestra di campionamento

color:  puo' essere FG_MONO o FG_RGB24

channel: canale video, solitamente settato a 0

Esempio:
---

FG_init(50000,15000,400,300,FG_MONO,0);

---

Attenzione al periodo di campionamento, e' buona regola non scendere
sotto i 40000 us ovvero 25 fps. Bisogna tenere presente che il frame
grabber usa massicciamente il bus PCI e il DMA per spostare il flusso
delle immagini. Va sempre settato il massimo periodo possibile che la
vostra applicazione richiede, evitate di sprecare risorse con grabbing
a 25 fps se poi non c'e' il tempo di gestire tutte le immagini raccolte.

Il pricipio base e' che nessuna immagine va sprecata. Per cui se il
processore permette di elaborare solo 1 immagine ogni 120000 us, non
settate il FG a 40000 us per poi usare 1 immagine su 3.

Per cercare di usare bene le risorse di sistema ed evitare una gestione
errara dei buffer del FG ho inserito una funzione virtuale

elaborate_frame_hook <fg.c>

che viene chiamata ad ogni inizio del ciclo di grabbing. Questa funzione
di default e' inizializzata a dummy_elaborate_frame, per cui non fa
niente, ma puo' essere usata dall'utente se e' richiesta una qualche 
elaborazione dell'immagine... puo' essere una copia del buffer nella 
memoria video per vedere il grabbing in azione o un complicato 
algoritmo di tracking.

Se ad esempio creo una funzione tipo

frame_elaborate(void *imageptr) {

  //Codice di elaborazione

}

dove lavoro l'immagine presa. Posso chiamare

FG_sethook(frame_elaborate)

per fare in modo che frame_elaborate venga chiamata automaticamente 
ad ogni immagine acquisita. Se ad esempio frame elaborate e' troppo 
complicata puo' capitare che venga mancata la deadline del task di 
grabbing (hard_task). A quel punto o si riducono i calcoli di questa 
funzione o si aumenta il periodo di grabbing.

Se non si ottengono deadline miss significa che tutto funziona bene
e sicuramente la funzione elabora sempre l'ultima immagine registrata.
Il grabber infatti usa il sistema del Double Buffer, per cui l'immagine 
su cui si lavora e' sempre completa ed integra.

Per passare parametri alla funzione frame_elaborate penso sia piu'
facile ricorrere a variabili globali piuttosto a passaggi di variabili 
generiche ridefinite volta per volta. Per cui la funzione di elaborazione 
deve essere sempre definita in questo modo:

void nome_funzione(void *imageptr);

Tenete conto che con FG_RGB24 invece di 1 byte per pixel nel buffer 
passate ad una modalita' RGB.

Dopo averlo inizializzato chiamate

FG_start_grabbing();

per farlo partire.

-------------------------------------------------------------------------------
Consigli per il Frame Grabber in generale.
-------------------------------------------------------------------------------

Giocando con i paramentri di luminosita', contrasto e saturazione si 
riesce a rendere l'immagine piu' semplice da elaborare (ad esempio per fare
il tracking di un oggetto in moto) senza ricorre a complicati algoritmi che
andrebbero a pesare sul processore.

Queste funzioni vengono chiamate da bttv_ioctl definita in bttv-driver.c

Prima di inizializzare il FG con la grafica provate a farlo partire in 
modalita' testo, cosi' l'output a schermo vi permette di vedere se la 
routine di init va a buon fine o se ci sono delle anomalie.

Una volta che sieti sicuri venga riconosciuta la vostra scheda e' buona 
regola inizializzare il FG DOPO LA SCHEDA VIDEO. Questo perche' ho 
riscontrato alcuni problemi con gli interrupt chiamati dalla VESA se il FG 
e' gia' in funzione.

-------------------------------------------------------------------------------
Programma di esempio: BTTVDEMO
-------------------------------------------------------------------------------