Controles estendidos da câmera

Controles estendidos usam o mecanismo KSPROPERTY para expor controles de câmera ao aplicativo.

A lista a seguir de controles estendidos padronizados (definidos pela Media Foundation) permite recursos adicionais da câmera do Windows:

• Metadados

• Prioridade de foco

• Estado de foco

• ROI (região de interesse estendida)

• Confirmação de foto

• Submodo de sequência de fotos

• Codificador JPEG EXIF e HW

• ISO inteiro

• Foco avançado

• Flash

• Zoom

• Modo de cenário

Alguns dos controles são expostos a aplicativos como controles assíncronos e outros são expostos como controles síncronos.

Controles síncronos

Para esses controles, o pipeline de captura emite uma estrutura de controle de câmera KSPROPERTY e espera que o driver retorne a solicitação de forma síncrona.

Controles assíncronos

Para esses controles, o pipeline de captura emite um KSPROPERTY, habilita um KSEVENT associado a essa propriedade e aguarda que o evento seja sinalizado. O driver deve concluir o KSPROPERTY de forma síncrona e usá-lo como um gatilho para iniciar uma operação assíncrona. Após a conclusão da operação assíncrona, o driver deve sinalizar o KSEVENT associado em que o pipeline de captura está aguardando. O pipeline de captura notifica o aplicativo sobre a conclusão da operação quando recebe o sinal.

Se um controle assíncrono puder ser cancelado, ele deverá especificar o sinalizador KSCAMERA_EXTENDEDPROP_FLAG_CANCELOPERATION no controle. Se o controle não puder ser cancelado, a operação do controle não deverá exceder 5 ms.

Esses controles estendidos fazem parte do seguinte conjunto de propriedades KS definido em ksmedia.h:

#define STATIC_KSPROPERTYSETID_ExtendedCameraControl \
     0x1CB79112, 0xC0D2, 0x4213, 0x9C, 0xA6, 0xCD, 0x4F, 0xDB, 0x92, 0x79, 0x72
DEFINE_GUIDSTRUCT("1CB79112-C0D2-4213-9CA6-CD4FDB927972", KSPROPERTYSETID_ExtendedCameraControl);
#define KSPROPERTYSETID_ExtendedCameraControl DEFINE_GUIDNAMED(KSPROPERTYSETID_ExtendedCameraControl);

Metadados

Para recuperar metadados, o componente de modo de usuário (DevProxy) deve consultar o driver quanto ao requisito de buffer de metadados. Depois que o componente do modo de usuário tiver essas informações, ele alocará o buffer de metadados apropriado para o driver preencher e retornar ao componente do modo de usuário.

O ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA, definido na enumeração KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY, é usado pelo cliente para consultar os requisitos de buffer de metadados, como o tamanho necessário de metadados, requisitos de alinhamento de memória e o tipo desejado de alocação de memória, na alocação de buffer de metadados.

Depois que o componente do modo usuário tiver obtido os requisitos de buffer de metadados do driver, ele alocará um buffer de metadados de tamanho apropriado com o alinhamento de memória especificado do pool de memória desejado. Esse buffer de metadados juntamente com o buffer de quadro real será enviado ao driver para processamento e depois será retornado ao componente no modo usuário quando estiver preenchido. Para cenários de múltiplas capturas, um buffer de metadados correspondente é alocado e entregue ao driver da câmera para cada quadro de buffer alocado.

A estrutura KSSTREAM_METADATA_INFO , juntamente com o sinalizador a seguir, é usada para enviar o buffer de metadados para o driver.

#define KSSTREAM_HEADER_OPTIONSF_METADATA           0x00001000

Depois que o buffer (metadados + quadro) é enfileirado no driver, o DevProxy envia uma estrutura de KSSTREAM_HEADER padrão, seguida por uma estrutura KS_FRAME_INFO e, em seguida, por uma estrutura KSSTREAM_METADATA_INFO. DevProxy mascarará ainda mais KSSTREAM_HEADER. OptionFlags com KSSTREAM_HEADER_OPTIONSF_METADATA antes de passar o buffer para baixo para o driver.

Se o driver não der suporte a metadados ou se KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA não for implementado, o controle de propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA falhará. Nesse caso, DevProxy não alocará um buffer de metadados e o conteúdo passado para o driver de DevProxy não conterá a estrutura KSSTREAM_METADATA_INFO .

Se o driver der suporte a metadados e o cliente não quiser metadados, o DevProxy não alocará o buffer de metadados nem passará KSSTREAM_METADATA_INFO ao enviar o buffer para o driver. Esse comportamento reduz a alocação desnecessária de memória de metadados se um aplicativo não quiser metadados em um determinado pino.

As estruturas a seguir descrevem o layout dos itens de metadados a serem preenchidos pelo driver da câmera no buffer de metadados.

• KSCAMERA_MetadataId

• KSCAMERA_METADATA_ITEMHEADER

• KSCAMERA_METADATA_PHOTOCONFIRMATION

A lista abaixo contém o layout de um item de metadados. Isso deve estar alinhado a 8 bytes.

• KSCAMERA_METADATA_ITEMHEADER

• Metadados

Os metadados de confirmação da foto são identificados por MetadataId_PhotoConfirmation. Quando presente, indica que o quadro de visualização associado é um quadro de confirmação de foto. Os metadados de confirmação da foto são analisados pelo DevProxy.

Os metadados personalizados são identificados por um MetadadosId que começa a partir de MetadataId_Custom_Start. O item de metadados personalizado pode conter um blob de metadados que represente um estado de foco e/ou rostos detectados para o pin de visualização, assim como EXIF e/ou os metadados OEM para um pin de imagem. O formato exato do blob personalizado é determinado pelo OEM que implementa o driver e o MFT0. O MFT0 é responsável por analisar o blob personalizado e anexar cada item de metadados como um atributo agrupado sob o recipiente de atributos MFSampleExtension_CaptureMetadata em um formato legível pelo pipeline de captura do MF e/ou WinRT.

Os imfAttributes a seguir são definidos em mfapi.h. Eles são exigidos pelo pipeline de captura de MF e/ou WinRT. Observe que o MFT0 não define nenhum atributo IMF para a confirmação de fotos, pois o frame de confirmação da foto não passará além do DevProxy.

Os MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttributes são criados e anexados a MFSampleExtension_CaptureMetadata pelo DevProxy, que contém um ponteiro para a interface IMFMediaBuffer associada ao buffer de metadados bruto (KSSTREAM_METADATA_INFO. Dados).

Quando o MFT0 recebe um IMFSample, ele obtém o buffer de metadados brutos do MF_CAPTURE_METADATA_FRAME_RAWSTREAM e analisa quaisquer itens de metadados personalizados adicionais, como estado de foco, e os converte em IMFAttributes correspondentes mencionados acima, anexando-os ao compartimento de atributos MFSampleExtension_CaptureMetadata. Os seguintes IMFAttributes devem ser transportados pelo pipeline do MF e por quaisquer MFTs fornecidos por terceiros:

Para acessar o buffer de metadados brutos, o MFT0 faz o seguinte:

1. Chama GetUnknown em MFSampleExtension_CaptureMetadata da interface IMFSample para obter a interface IMFAttributes para o conjunto de atributos.

2. Na interface IMFAttributes obtida da etapa anterior, chama GetUnknown em MF_CAPTURE_METADATA_FRAME_RAWSTREAM para obter a interface IMFMediaBuffer.

3. Chama Lock para obter o buffer de metadados bruto associado ao IMFMediaBuffer.

Para adicionar os IMFAttributes necessários ao contêiner de atributos MFSampleExtension_CaptureMetadata, o MFT0 faz o seguinte:

1. Chama GetUnknown em MFSampleExtension_CaptureMetadata da interface IMFSample para obter a interface IMFAttributes para o conjunto de atributos.

2. Chama SetUINT32, SetBlob ou SetUnknown em MF_CAPTURE_METADATA_XXX da interface IMFAttributes obtida da etapa anterior com base no GUID e no tipo de dados especificados na tabela acima.

Atributos de metadados obrigatórios

A lista completa de atributos de metadados disponíveis pode ser encontrada em Atributos de Metadados de Estatísticas de Captura

Prioridade de foco

A ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSPRIORITY é o único controle associado à DDI de prioridade de foco.

Estado de foco

O ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSSTATE é o único controle associado à DDI do estado de foco.

ROI de região de interesse estendida

As seguintes IDs de propriedade são os controles associados à ROI DDI:

• KSPROPERTY_CAMERACONTROL_EXTENDED_ROI_CONFIGCAPS

• KSPROPERTY_CAMERACONTROL_EXTENDED_ROI_ISPCONTROL

Confirmação de foto

A ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOCONFIRMATION é o único controle associado à DDI de confirmação de foto.

Submodo de sequência de fotos

A propriedade ID KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOMODE é o único controle associado à sequência de fotos DDI.

Codificador JPEG de hardware e EXIF

O pipeline não é necessário para processar ou distorcer dados EXIF para o codificador JPEG de hardware; portanto, o formato de dados EXIF é fornecido pelo driver, MFT0 e o codificador JPEG de hardware do OEM. Os parceiros OEM podem definir qualquer GUID de atributo customizado e tipo de variante para o atributo EXIF e anexá-lo ao recipiente de atributos MFSampleExtension_CaptureMetaData para que ele seja consumido pelos componentes OEM. Se um codificador HW JPEG estiver disponível, o componente de saída de fotos do pipeline carregará o codificador HW JPEG e configurará os dados EXIF presentes no recipiente de atributos MFSampleExtension_CaptureMetaData no codificador HW JPEG como uma opção de codificação EXIF usando o método IPropertyBag2::Write.

O conjunto de propriedades de opção do codificador contém uma matriz de estruturas PROPBAG2 que especificam as opções de codificação disponíveis. A opção de encoder EXIF definida no encoder HW JPEG é identificada pela seguinte propriedade no pacote de propriedades da opção de encoder:

O bolsa de atributos MFSampleExtension_CaptureMetaData só pode conter qualquer subatributo EXIF definido pelo OEM que o codificador JPEG MFT0 e HW possa ler para armazenar os dados EXIF. Para passar dados EXIF do driver para o codificador HW JPEG, o driver e o MFT0 devem fazer o seguinte:

1. O driver fornece metadados EXIF personalizados no buffer de metadados fornecido pelo pipeline. Isso é anexado a MFSampleExtension_CaptureMetadata como um MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttribute por DevProxy quando a amostra é retornada ao DevProxy.

2. Quando o MFT0 recebe um IMFSample, ele obtém o buffer de metadados brutos de MF_CAPTURE_METADATA_FRAME_RAWSTREAM e interpreta o item de metadados EXIF personalizado e o transforma em um IMFAttribute definido pelo OEM e o anexa ao conjunto de atributos MFSampleExtension_CaptureMetadata.

Para passar os dados EXIF do MFT0 para o codificador JPEG de hardware, o módulo de captura de fotos do pipeline faz o seguinte:

1. Chama GetUnknown em MFSampleExtension_CaptureMetadata de IMFSample para obter a interface IMFAttributes para o conjunto de atributos ao receber o IMFSample.

2. Chama IPropertyBag2::Write para definir a propriedade de opção do codificador, identificada por SampleMetadata, para o codificador JPEG de hardware. A propriedade de opção do codificador contém a interface IMFAttributes obtida da etapa anterior. Essa interface contém todos os sub atributos personalizados, incluindo o sub atributo OEM EXIF e os sub atributos padronizados na seção Metadados discutida anteriormente neste tópico.

Para recuperar os dados EXIF para processamento adicional, o codificador JPEG do HW faz o seguinte:

1. Chama IPropertyBag2::Read para recuperar o valor da propriedade identificada pelo nome SampleMetadata e pelo tipo VT_UNKNOWN. Quando retornado, o VARIANT.punkVal recebe a interface IMFAttributes para MFSampleExtension_CaptureMetadata.

2. Chama GetBlob ou GetUnknown no sub atributo OEM EXIF da interface obtida da etapa anterior para obter o blob de dados EXIF com base no GUID e no tipo de dados do sub atributo OEM EXIF.

Miniatura

MFT0 não precisa gerar miniaturas para o driver da câmera. Espera-se que o aplicativo de câmera gere sua própria miniatura. A miniatura pode ser produzida a partir da imagem de confirmação de foto, do codificador JPEG de hardware ou do redimensionamento de uma imagem de tamanho completo. Isso cabe aos desenvolvedores de aplicativos. Para manter a compatibilidade da API e do aplicativo com aplicativos do Windows 8.1, o driver de câmera não deve implementar o controle KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOTHUMBNAIL .

Número inteiro ISO

A ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_ISO_ADVANCED é o único controle associado ao INTEIRO ISO DDI.

Foco avançado

O ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSMODE é o único controle associado ao ISO DDI inteiro.

Flash

A ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_FLASHMODE é o único controle associado ao DDI flash.

Zoom

A ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM é o único controle associado à DDI de zoom.

Modo de cena

O ID da propriedade KSPROPERTY_CAMERACONTROL_EXTENDED_SCENEMODE é o único controle associado à DDI do modo cena.