Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
A partire da Windows Threshold, verrà esposta una nuova API Lamp WinRT che consente di programmare flash della fotocamera senza la necessità di creare un'istanza di Windows.Media.Capture.MediaCapture . In questo modo, uno sviluppatore può scrivere un'applicazione torcia (solo a scopo di illuminazione) utilizzando la minima quantità di risorse, inclusa l'energia, in modo che un dispositivo informatico possa essere ottimizzato per le prestazioni e la durata della batteria.
A tale scopo, un IHV/OEM implementa un driver WDM che supporta le funzioni seguenti:
Consentire al sistema di enumerare tutti i dispositivi flash.
Attivare/disattivare la torcia per dispositivo.
Se applicabile, regolare l'intensità della luce (simile a PowerPercent) per dispositivo.
Se applicabile, specificare il colore chiaro per dispositivo.
In termini di funzionalità, l'elenco precedente si sovrappone in modo significativo a quello di MediaCapture (ad esempio , FlashControl e TorchControl). Inoltre, lo stesso hardware flash viene utilizzato sia per la lampada che per il flash durante l'acquisizione. Di conseguenza, si consiglia a un IHV/OEM di supportare entrambi i tipi di operazioni usando un singolo driver WDM per controllare esclusivamente il flash. La figura seguente illustra il concetto:
Nell'esempio precedente è presente una sola istanza hardware flash (mostrata come) ed è gestita da un singolo driver flash KMDF. Il driver flash espone due interfacce del dispositivo, ognuna delle quali è destinata a un tipo specifico di client (o API WinRT). Ad esempio, data la figura precedente:
L'API WinRT di acquisizione multimediale e il minidriver AVStream comunicano sempre con il driver flash tramite l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH, mentre
L'API Lamp WinRT comunica sempre con il driver flash tramite l'interfaccia GUID_DEVINTERFACE_LAMP.
Poiché l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH viene usata da un minidriver AVStream specifico del fornitore, un IHV/OEM è libero di definirne le funzionalità in modo che non vi sarà alcuna restrizione imposta da Windows.
Tuttavia, Microsoft standardizzerà l'interfaccia, GUID_DEVINTERFACE_LAMP, perché verrà usata dall'API Lamp WinRT. Per ulteriori informazioni su GUID_DEVINTERFACE_LAMP, consultare GUID della classe dell'interfaccia del dispositivo
Casi d'uso della concorrenza
Condivisione di flash tra fotocamere e applicazioni flashlight
Un flash della fotocamera viene in genere considerato come una periferica subordinata a un dispositivo di acquisizione . Non è previsto che venga condiviso con scenari senza fotocamera mentre l'acquisizione è in esecuzione. Per complicare ulteriormente, il numero di unità flash su uno chassis è estremamente limitato, in modo che, in pratica, non ci sarà spazio di memoria flash dedicato esclusivamente alla funzione di torcia.
Dal punto di vista del software, il precedente impone una sfida in cui un'applicazione fotocamera e un'applicazione torcia possono coesistere e accedere al flash contemporaneamente. Ad esempio, in teoria, un utente può commutare lo stato del LED tramite un'applicazione torcia mentre è attivo il mirino della fotocamera.
Poiché la fotocamera richiede controlli precisi sul flash per supportare lo stato attivo e l'acquisizione, può essere difficile per il driver risolvere le richieste flash di interessi in conflitto garantendo al tempo stesso la qualità dell'immagine. Per risolvere questo problema, i criteri seguenti vengono applicati a livello di sistema come contratto:
Se una sessione di acquisizione viene avviata per la prima volta, un'applicazione flashlight non può modificare il flash fino all'arresto dell'acquisizione.
Un'applicazione flashlight può comunque acquisire un handle per il driver flash, ma qualsiasi operazione che modifica lo stato flash restituisce un errore immediato.
Quando l'acquisizione si arresta in modo che il minidriver AVStream rilasci il flash, il driver flash è necessario per pubblicare una notifica PnP (vedere GUID_LAMP_RESOURCES_AVAILABLE in Notifiche asincrone) che indica che l'hardware sottostante è ora diventato disponibile. Dopo aver ricevuto tale notifica, un'applicazione torcia è autorizzata a programmare la modalità di illuminazione di conseguenza.
Se un'applicazione flashlight viene avviata per la prima volta, una sessione di acquisizione è libera di dirottare l'hardware flash senza consenso esplicito.
Con "hijacking", si intende che un IHV/OEM può implementare un protocollo arbitrario (possibilmente tramite l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH) in modo che il minidriver AVStream sia autorizzato ad acquisire flash come se l'hardware non venga usato affatto.
Quando si verifica un hijack, il driver flash deve pubblicare un'altra notifica PnP (vedere GUID_LAMP_RESOURCES_LOST in Notifiche asincrone) che indica che il flash è stato riassegnato involontariamente in modo che l'applicazione flashlight possa agire di conseguenza (aggiornando ad esempio l'interfaccia utente)
Condivisione di flash tra più applicazioni flashlight
Se la fotocamera non è coinvolta e due applicazioni flashlight vengono eseguite in successione, il driver deve mantenere la manutenzione del primo client che ha già acquisito l'interfaccia GUID_DEVINTERFACE_LAMP e rifiutare tutti i client aggiuntivi fino alla prima versione finale dell'interfaccia.
In altre parole, l'interfaccia GUID_DEVINTERFACE_LAMP consente solo un client torcia alla volta e il primo client che acquisisce l'interfaccia impedisce agli altri di operare (esclusi fotocamera/AVStream).
Classe GUID dell'interfaccia dispositivo
Un driver flash IHV/OEM in grado di supportare la torcia indipendentemente da MediaCapture deve registrarsi con il GUID della classe di interfaccia del dispositivo, GUID_DEVINTERFACE_LAMP.
| Attributo | Impostazione |
|---|---|
| Identificatore | GUID_DEVINTERFACE_LAMP |
| Classe GUID | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
Il GUID della classe di interfaccia del dispositivo GUID_DEVINTERFACE_CAMERA_FLASH può essere definito dagli IHVs/OEMs. Tuttavia, il GUID della classe dell'interfaccia del dispositivo, GUID_DEVINTERFACE_LAMP, è definito da Windows.
Per contratto, un driver che espone l'interfaccia del dispositivo, GUID_DEVINTERFACE_LAMP, è necessario per supportare le funzioni seguenti (vedere le sezioni successive per informazioni dettagliate):
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} : ottiene tutte le modalità (ad esempio, solo bianco e colore) supportate dall'hardware sottostante
IOCTL_LAMP_{GET|SET}_MODE : ottiene o imposta la modalità corrente
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} : ottiene o imposta l'intensità della luce
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT : ottiene o imposta lo stato flash (ad esempio, ON/OFF)
Se un dispositivo ha più di un hardware flash di tipi diversi (ad esempio, sia un LED bianco che un flash Xenon) e questi hardware sono controllati da driver flash diversi, ogni driver espone la stessa interfaccia GUID_DEVINTERFACE_LAMP con un ID istanza univoco.
Proprietà dell'interfaccia del dispositivo
Poiché un dispositivo di calcolo può avere zero o più dispositivi flash su pannelli diversi, l'API Lamp WinRT necessita di un meccanismo per enumerare tutto l'hardware flash in modo che un'applicazione possa programmare un'istanza specifica.
Per supportare l'enumerazione del dispositivo, analogamente al driver della fotocamera, il driver flash è necessario per associare una struttura ACPI _PLD v2 a ogni interfaccia GUID_DEVINTERFACE_LAMP come dati delle proprietà dell'interfaccia.
IOCTL_LAMP_GET_CAPABILITIES_WHITE
La richiesta di I/O IOCTL_LAMP_GET_CAPABILITIES_WHITE esegue una query sulle funzionalità del flash quando il dispositivo è configurato per generare luce bianca.
Definizione
#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_CAPABILITIES_WHITE. Per informazioni dettagliate, vedere osservazioni
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp->AssociatedIrp.SystemBuffer.
Parametri di output
Irp-AssociatedIrp.SystemBuffer> è pieno di tutte le funzionalità supportate dall'hardware flash.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore corretto. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere il buffer.
Osservazioni:
Per requisito, è necessario un flash il cui driver supporta l'interfaccia GUID_DEVINTERFACE_LAMP per supportare l'emissione di luce bianca. Il payload di questo IOCTL è definito come segue:
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
Il campo IsLightIntensityAdjustable indica se è possibile programmare il livello di luminanza. Se questo campo restituisce false, significa che il dispositivo sottostante supporta solo l'interruttore on/off e l'intensità della luce non può essere modificata.
IOCTL_LAMP_GET_CAPABILITIES_COLOR
La richiesta di I/O IOCTL_LAMP_GET_CAPABILITIES_COLOR esegue una query sulle funzionalità del flash quando il dispositivo è configurato per emettere luce colorata.
Definizione
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_CAPABILITIES_COLOR. Per informazioni dettagliate, vedere osservazioni
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp->AssociatedIrp.SystemBuffer.
Parametri di output
Irp-AssociatedIrp.SystemBuffer> è pieno di tutte le funzionalità supportate dall'hardware flash.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere il buffer.
Osservazioni:
Il payload di questo IOCTL è definito come segue:
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
Il primo campo IsSupported indica se il flash può generare luce di colore. Se hardware non supporta luce colorata, il driver dovrebbe impostare questo campo su false.
Il secondo campo IsLightIntensityAdjustable indica se è possibile programmare il livello di luminanza. Se il flash non supporta la luce colorata (ad esempio, IsSupported valuta false), un client deve ignorare il valore di IsLightIntensityAdjustable.
IOCTL_LAMP_GET_MODE
La richiesta di I/O IOCTL_LAMP_GET_MODE esegue una query sulla modalità con cui il flash è attualmente configurato.
Definizione
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_MODE, definito come segue:
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp.AssociatedIrp.SystemBuffer>.
Parametri di output
Irp->AssociatedIrp.SystemBuffer viene riempito con un valore LAMP_MODE.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato. Imposterà Irp->IoStatus.Information al numero di byte necessari per contenere un valore DWORD.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
IOCTL_LAMP_SET_MODE
La richiesta di I/O IOCTL_LAMP_SET_MODE imposta la modalità di funzionamento del flash.
Definizione
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_MODE.
Parametri di output
Nessuno.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
IOCTL_LAMP_GET_INTENSITY_WHITE
La richiesta di I/O IOCTL_LAMP_GET_INTENSITY_WHITE esegue una query sull'intensità della luce quando il flash è configurato per generare luce bianca.
Definizione
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp->AssociatedIrp.SystemBuffer punta a una struttura LAMP_INTENSITY_WHITE. Per informazioni dettagliate, vedere osservazioni
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp.AssociatedIrp.SystemBuffer.
Parametri di output
Irp-AssociatedIrp.SystemBuffer> viene riempito con le informazioni sull'intensità della luce.
Blocco di stato di I/O
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Osservazioni:
Il tipo di payload di questo IOCTL è definito come segue:
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
Il campo Valore è l'intensità della luce bianca in percentuale compresa tra 0 e 100 inclusi.
IOCTL_LAMP_SET_INTENSITY_WHITE
La richiesta di I/O IOCTL_LAMP_SET_INTENSITY_WHITE imposta il flash sull'intensità di luce specificata.
Definizione
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp>-AssociatedIrp.SystemBuffer indica una struttura LAMP_INTENSITY_WHITE (vedere IOCTL_LAMP_GET_INTENSITY_WHITE per informazioni dettagliate).
Parametri di output
Nessuno.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
IOCTL_LAMP_GET_INTENSITY_COLOR
La richiesta di I/O IOCTL_LAMP_GET_INTENSITY_COLOR esegue una query sull'intensità della luce quando il flash è configurato per generare la luce del colore.
Definizione
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp->AssociatedIrp.SystemBuffer punta a una struttura LAMP_INTENSITY_COLOR. Per informazioni dettagliate, vedere osservazioni
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp->AssociatedIrp.SystemBuffer.
Parametri di output
Irp-AssociatedIrp.SystemBuffer> viene riempito con le informazioni sull'intensità della luce.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Osservazioni:
Il tipo di payload di questo IOCTL è definito come segue:
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_COLOR.
typedef struct LAMP_INTENSITY_COLOR
{
BYTE Red; // Red light intensity in percentage (0-100)
BYTE Green; // Green light intensity in percentage (0-100)
BYTE Blue; // Blue light intensity in percentage (0-100)
} LAMP_INTENSITY_COLOR;
IOCTL_LAMP_SET_INTENSITY_COLOR
La richiesta di I/O IOCTL_LAMP_SET_INTENSITY_COLOR imposta il flash sull'intensità di luce specificata.
Definizione
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp->AssociatedIrp.SystemBuffer punta a una struttura LAMP_INTENSITY_COLOR (vedere IOCTL_LAMP_GET_INTENSITY_COLOR per informazioni dettagliate).
Parametri di output
Nessuno.
Blocco di stato di I/O
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
IOCTL_LAMP_GET_EMITTING_LIGHT (Ottieni la luce emessa)
Lo IOCTL_LAMP_GET_EMITTING_LIGHT è una richiesta di I/O, per verificare se la luce (flash) è accesa.
Definizione
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo BOOLEAN.
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp->AssociatedIrp.SystemBuffer.
Parametri di output
Irp-AssociatedIrp.SystemBuffer> viene riempito con lo stato flash con TRUE, il che significa che il flash è attivato (ad esempio, emettendo luce); FALSE in caso contrario.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp->IoStatus.Information sul numero di byte necessari per contenere un valore DWORD.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
IOCTL_LAMP_SET_EMITTING_LIGHT
La richiesta di I/O IOCTL_LAMP_SET_EMITTING_LIGHT attiva o disattiva la luce (flash).
Definizione
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
Parametri di input
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo BOOLEAN con TRUE che indica ON; FALSE in caso contrario.
Parametri di output
Nessuno.
Blocco di stato di I/O
Il driver imposta Irp->IoStatus.Status su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Notifiche asincrone
Come descritto in Casi d'uso della concorrenza, il driver flash è necessario per inviare notifiche PnP per segnalare la disponibilità delle risorse. A tale scopo, è possibile chiamare IoReportTargetDeviceChange (o IoReportTargetDeviceChangeAsynchronous) con i GUID seguenti a seconda dello scenario:
La risorsa flash è stata rimossa perché viene avviata una sessione di acquisizione (o un'altra applicazione flashlight):
Attributo Impostazione Identificatore GUID_LAMP_RESOURCES_LOST Classe GUID {F770E98C-4403-48C9-B1D2-4EEC302E41F} La risorsa flash è ora disponibile:
Attributo Impostazione Identificatore GUID_LAMP_RESOURCES_AVAILABLE Classe GUID {185FE7CE-2616-481B-9094-20BB893ACD81}