Partilhar via


Atributos de Metadados das Estatísticas de Captura

A tabela abaixo resume as estatísticas de captura disponíveis dos IMFAttributes para o pacote de atributos de metadados MFT0 MFSampleExtension_CaptureMetaData, abrangendo pré-visualização, vídeo e captura de imagens estáticas.

As estatísticas de captura listadas para imagens fixas são obrigatórias para todas as fotos capturadas, salvo indicação em contrário. As estatísticas de captura listadas para visualização e vídeo devem ser fornecidas da melhor forma possível, e o controlador poderá ou não fornecer todas as estatísticas de captura em todos os quadros, dependendo da disponibilidade e das considerações de desempenho.

Nome Tipo Código PIN Descrição
MF_CAPTURE_METADATA_FOCUSSTATE UINT32 Pré-visualização Este atributo contém o estado de foco atual que pode ter um dos seguintes valores.
MF_CAPTURE_METADATA_SENSORFRAMERATE UINT64 Pré-visualização Este atributo contém a taxa de leitura do sensor medida em hertz quando um quadro de visualização é capturado, que consiste em um valor de numerador no 32 bit superior e um valor de denominador no 32 bit inferior.
MF_CAPTURE_METADATA_FACEROIS Blob Prévia, Vídeo Este atributo contém as informações do retângulo facial detetadas pelo motorista.
MF_CAPTURE_METADATA_FACEROITIMESTAMPS Blob Pré-visualização, Vídeo Este atributo contém as informações de data e hora para os ROIs faciais identificados em MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS Blob Pré-visualização, Vídeo Este atributo contém o estado de pestanejo e/ou expressão facial dos ROIs faciais identificados em MF_CAPTURE_METADATA_FACEROIS
MF_CAPTURE_METADATA_TEMPO_DE_EXPOSIÇÃO UINT64 Pré-visualização, Ainda Este atributo contém o tempo de exposição aplicado em 100 nanossegundos
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION Blob Prévia, Ainda Este atributo contém um indicador de etapa de compensação EV e um valor de compensação EV em unidades da etapa que foi aplicado ao controlador quando a foto foi capturada.
MF_CAPTURE_METADATA_ISO_SPEED UINT32 Pré-visualização, Imagem Fixa Este atributo contém o valor de velocidade ISO aplicado como um inteiro.
MF_CAPTURE_METADATA_LENS_POSITION UINT32 Pré-visualização, Imagem estática Este atributo contém a posição lógica da lente quando o foco foi aplicado à foto capturada. Este valor não tem uma unidade específica.
MF_CAPTURE_METADATA_SCENE_MODE UINT64 Ainda Este atributo contém o modo de cena aplicado como um indicador do tipo UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX.
MF_CAPTURE_METADATA_FLASH UINT32 (Booleano) Pré-visualização, Estável Este atributo contém um valor booleano que contém o estado flash. Um valor de 1 especifica que o flash está ligado e um valor de 0 especifica que o flash está desligado para a foto capturada.
MF_CAPTURE_METADATA_FLASH_POWER UINT32 Ainda [Opcional] Este atributo contém a potência do flash aplicada como um valor percentual entre 0 e 100.
MF_CAPTURE_METADATA_WHITEBALANCE UINT32 (Kelvin) Pré-visualização, Imagem Fixa Este atributo contém o balanço de branco aplicado como um valor em Kelvin.
MF_CAPTURE_METADATA_ZOOMFACTOR UINT32 (Q16) Ainda Este atributo contém o valor de zoom aplicado e é o mesmo valor que pode ser consultado a partir de KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM em uma chamada GET. O valor deve estar em Q16.
MF_CAPTURE_METADATA_EXIF Blob Ainda [Opcional] Este atributo contém metadados EXIF conforme especificado na definição de blob na seção
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID UINT32 Ainda [Opcional] Este atributo contém o ID do quadro para o quadro correspondente na sequência de fotos variável. Este atributo só é definido para uma captura de sequência de fotos variável.
MF_CAPTURE_METADATA_ISO_GAINS Blob Pré-visualização Este atributo contém os ganhos analógicos e digitais aplicados ao sensor quando o fotograma de pré-visualização foi capturado. Isto não tem unidade.
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS Blob Pré-visualização Este atributo contém os ganhos de balanço de branco aplicados a R, G, B pelo sensor e\ou ISP quando o quadro de visualização foi capturado. Isto não tem unidade.
MF_CAPTURE_METADATA_HISTOGRAM Blob Pré-visualização Este atributo contém o histograma quando um quadro de visualização é capturado.
MF_CAPTURE_METADATA_FRAME_ILLUMINATION UINT64 Pino IR usado para Hello Este atributo para câmaras IR especifica se os quadros estão a utilizar iluminação IR ativa e devem ser usados em conjunto com FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION.
Qualquer GUID personalizado Qualquer tipo de variante Este atributo contém os dados personalizados associados ao GUID personalizado

MF_CAPTURE_METADATA_FOCUSSTATE

MF_CAPTURE_METADATA_FOCUSSTATE atributo contém o estado de foco atual que pode ter um dos seguintes valores.

typedef enum
{
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_UNINITIALIZED = 0,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_LOST,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_SEARCHING,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FOCUSED,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FAILED,
} KSCAMERA_EXTENDEDPROP_FOCUSSTATE;

MF_CAPTURE_METADATA_SENSORFRAMERATE

O atributo MF_CAPTURE_METADATA_SENSORFRAMERATE contém a taxa de leitura do sensor medida em hertz quando um fotograma de pré-visualização é capturado, que consiste em um valor de numerador nos 32 bits superiores e um valor de denominador nos 32 bits inferiores.

MF_CAPTURE_METADATA_FACEROIS

O atributo MF_CAPTURE_METADATA_FACEROIS contém as informações sobre o retângulo facial detetadas pelo controlador. Por padrão, o driver\MFT0 deve fornecer as informações faciais no fluxo de visualização. Se o driver anunciar a capacidade em outros fluxos, driver\MFT deve fornecer as informações de rosto nos fluxos correspondentes se o aplicativo permitir a deteção de rosto nesses fluxos. Quando a estabilização de vídeo está habilitada no driver, as informações de rosto devem ser fornecidas após a estabilização de vídeo. As seguintes estruturas de dados descrevem o formato blob para MF_CAPTURE_METADATA_FACEROIS. O rosto dominante deve ser a primeira informação de FaceRect no blob.

typedef struct tagFaceRectInfoBlobHeader
{
    ULONG Size;             // Size of this header + all FaceRectInfo following
    ULONG Count;            // Number of FaceRectInfo’s in the blob
} FaceRectInfoBlobHeader;

typedef struct tagFaceRectInfo
{
    RECT Region;            // Relative coordinates on the frame that face detection is running (Q31 format)
    LONG ConfidenceLevel;   // Confidence level of the region being a face ([0, 100])
} FaceRectInfo;

Observe que as estruturas FaceRectinfoBlobHeader e FaceRectInfo descrevem apenas o formato de blob para o atributo MF_CAPTURE_METADATA_FACEROIS. A estrutura de itens de metadados para ROIs de face (carga útil de metadados KSCAMERA_METADATA_ITEMHEADER + ROIs de face) fica a cargo do driver e deve estar alinhada a 8 bytes.

Por design, se um fluxo estiver configurado com a deteção de rosto ativada e a cena em questão não contiver rostos durante a captura, o motorista ainda será obrigado a anexar um atributo de MF_CAPTURE_METADATA_FACEROIS "fictício" a cada amostra que não tenha informações de rosto associadas a ela. (Um atributo ROI de face "simulado" tem o campo Count da estrutura FaceRectInfoBlobHeader definido como zero.)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

O atributo MF_CAPTURE_METADATA_FACEROITIMESTAMPS contém as informações de carimbo de data/hora para os ROIs faciais identificados em MF_CAPTURE_METADATA_FACEROIS. Para o dispositivo que não pode fornecer a data e hora para ROIs faciais, esse atributo deve ser omitido.

A estrutura de dados seguinte descreve o formato de blob para MF_CAPTURE_METADATA_FACEROITIMESTAMPS.

typedef struct tagMetadataTimeStamps
{
    ULONG Flags;            // Bitwise OR of MF_METADATATIMESTAMPS_XXX flags
    LONGLONG Device;        // QPC time for the sample where the face rect is derived from (in 100ns)
    LONGLONG Presentation;  // PTS for the sample where the face rect is derived from (in 100ns)
} MetadataTimeStamps;

Para o campo Sinalizadores, definiremos os seguintes sinalizadores de bit para indicar qual carimbo de data/hora é válido. MFT0 deve definir Flags como MF_METADATATIEMSTAMPS_DEVICE e o tempo QPC apropriado para o Dispositivo, caso o driver forneça os metadados do carimbo de data/hora para as ROIs faciais.

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

Observe que MetadataTimeStamps struct descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_FACEROITIMESTAMPS. A estrutura do item de metadados para a marca temporal (KSCAMERA_METADATA_ITEMHEADER + carga útil de metadados da marca temporal) é da responsabilidade do driver e deve estar alinhada a 8 bytes.

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

O atributo MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS contém o estado de piscar e/ou expressão facial para os ROIs faciais identificados em MF_CAPTURE_METADATA_FACEROIS.  Para o dispositivo que não suporta piscar e\ou deteção de expressão facial, esse atributo deve ser omitido.

A estrutura de dados abaixo descreve o formato de bloco para MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS.

Observe que as estruturas FaceCharacterizationBlobHeader e FaceCharacterization descrevem apenas o formato de blob para o atributo MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS. A estrutura do item de metadados para as caracterizações de face (KSCAMERA_METADATA_ITEMHEADER + carga útil de metadados das caracterizações de face) fica a cargo do driver e deve estar alinhada a 8 bytes.

typedef struct tagFaceCharacterizationBlobHeader
{
    ULONG Size;     // Size of this header + all FaceCharacterization following
    ULONG Count;    // Number of FaceCharacterization’s in the blob. Must match the number of FaceRectInfo’s in FaceRectInfoBlobHeader
} FaceCharacterizationBlobHeader;

typedef struct tagFaceCharacterization
{
    ULONG BlinkScoreLeft;   // [0, 100]. 0 indicates no blink for the left eye. 100 indicates definite blink for the left eye
    ULONG BlinkScoreRight;  // [0, 100]. 0 indicates no blink for the right eye. 100 indicates definite blink for the right eye
    ULONG FacialExpression; // Any one of the MF_METADATAFACIALEXPRESSION_XXX defined
    ULONG FacialExpressionScore; // [0, 100]. 0 indicates no such facial expression as identified. 100 indicates definite such facial expression as defined
} FaceCharacterization;

O seguinte define a possível expressão facial que pode ser detetada.  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

Se o atributo MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS estiver presente, o número e a ordem das entradas FaceCharacterization no blob devem corresponder ao número e à ordem das entradas FaceRectInfo no blob de MF_CAPTURE_METADATA_FACEROIS.   Cada entrada FaceCharacterization representa o estado de piscar e\ou expressão facial do rosto na entrada FaceRectInfo correspondente no mesmo índice.

A figura abaixo ilustra os layouts de um blob de caracterização de rosto e um blob de ROIs de rosto de quatro faces: o primeiro sem piscar nem sorrir, o segundo piscando o olho esquerdo, o terceiro sorrindo, e o quarto piscando (ambos os olhos) e sorrindo.

MF_CAPTURE_METADATA_EXPOSURE_TIME

O atributo MF_CAPTURE_METADATA_EXPOSURE_TIME contém o tempo de exposição aplicado ao sensor quando a pré-visualização e/ou a moldura da foto foram capturadas, sendo um UINT64 e medido em unidades de 100ns.

Metadados de Captura MF - Compensação de Exposição

O atributo MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION contém um sinalizador de etapa de compensação EV e um valor de compensação EV em unidades da etapa aplicadas ao sensor quando a visualização e/ou moldura da foto foram capturadas.

A estrutura de dados abaixo descreve o formato de blob para MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION.

typedef struct tagCapturedMetadataExposureCompensation
{
    UINT64 Flags;   // KSCAMERA_EXTENDEDPROP_EVCOMP_XXX step flag
    INT32 Value;    // EV Compensation value in units of the step
} CapturedMetadataExposureCompensation;

Observe que a struct CapturedMetadataExposureCompensation descreve o formato de blob apenas para o atributo MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION. A estrutura de itens de metadados para compensação de EV (KSCAMERA_METADATA_ITEMHEADER + carga útil de metadados de compensação de EV) fica a cargo do driver e deve ter um alinhamento de 8 bytes.

MF_CAPTURE_METADATA_ISO_SPEED

MF_CAPTURE_METADATA_ISO_SPEED atributo contém o valor de velocidade ISO aplicado ao sensor quando o fotograma de pré-visualização e/ou o quadro fotográfico foi capturado. Isto não tem unidade.

MF_CAPTURE_METADATA_ISO_GAINS

O atributo MF_CAPTURE_METADATA_ISO_GAINS contém os ganhos analógicos e digitais aplicados ao sensor quando o quadro de visualização foi capturado. Isto não possui unidade.

A estrutura de dados apresentada abaixo descreve o formato blob para o MF_CAPTURE_METADATA_ISO_GAINS.

typedef struct tagCapturedMetadataISOGains
{
    FLOAT AnalogGain;
    FLOAT DigitalGain;
} CapturedMetadataISOGains;

Observe que CapturedMetadataISOGains struct descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_ISO_GAINS. A estrutura de itens de metadados para ganhos ISO (KSCAMERA_METADATA_ITEMHEADER + carga útil de metadados de ganhos ISO) depende do controlador e deve ter alinhamento de 8 bytes.

MF_CAPTURE_METADATA_LENS_POSITION

MF_CAPTURE_METADATA_LENS_POSITION atributo contém a posição lógica da lente quando a visualização e\ou a moldura da foto foi capturada, que é sem unidade. Este é o mesmo valor que pode ser consultado a partir de KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS em uma chamada GET.

MF_CAPTURE_METADATA_SCENE_MODE

O atributo MF_CAPTURE_METADATA_SCENE_MODE contém o modo de cena aplicado à foto capturada, que é um indicador KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX de 64 bits.

MF_CAPTURE_METADATA_FLASH

O atributo MF_CAPTURE_METADATA_FLASH contém um valor booleano quando um quadro de visualização ou de foto é capturado, com 1 significando flash ligado e 0 significando flash desligado.

MF_CAPTURA_DADOS_FLASH_POTÊNCIA

MF_CAPTURE_METADATA_FLASH_POWER atributo contém a potência de flash aplicada à foto capturada, que é um valor no intervalo de [0, 100]. Este atributo deve ser omitido se o driver não suportar potência ajustável do flash.

MF_CAPTURE_METADATA_WHITEBALANCE

O atributo MF_CAPTURE_METADATA_WHITEBALANCE contém o balanço de brancos aplicado ao sensor quando a pré-visualização e/ou o quadro da foto foi capturado, que é um valor em Kelvin.

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

O atributo MF_CAPTURE_METADATA_WHITEBALANCE_GAINS contém os ganhos de balanço de branco aplicados ao R, G e B pelo sensor e/ou pelo ISP quando o quadro de pré-visualização foi capturado. Esta é uma unidade sem unidade.

A estrutura de dados abaixo descreve o formato de blob para MF_CAPTURE_METADATA_WHITEBALANCE_GAINS.

typedef struct tagCapturedMetadataWhiteBalanceGains
{
    FLOAT R;
    FLOAT G;
    FLOAT B;
} CapturedMetadataWhiteBalanceGains;

Observe que CapturedMetadataWhiteBalanceGains struct descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_WHITEBALANCE_GAINS. A estrutura dos itens de metadados para ganhos do balanço de brancos (KSCAMERA_METADATA_ITEMHEADER + carga útil dos metadados de ganhos do balanço de brancos) fica a cargo do driver e deve estar alinhada a 8 bytes.

MF_CAPTURE_METADATA_ZOOMFACTOR

MF_CAPTURE_METADATA_ZOOMFACTOR atributo contém o valor de zoom aplicado à foto capturada, que é o mesmo valor que pode ser consultado a partir de KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM em uma chamada GET. Isso deve ser no Q16.

MF_CAPTURE_METADATA_EXIF

MF_CAPTURE_METADATA_EXIF contém metadados EXIF conforme especificado na Seção 3.1 (Definição de Blob). MFT0 deve extrair os metadados EXIF brutos, que são identificados como um item de metadados personalizados (MetadataId >= MetadataId_Custom_Start), do buffer de MF_CAPTURE_METADATA_FRAME_RAWSTREAM fornecido pelo driver. MFT0 deve então converter os dados brutos em um atributo MF_CAPTURE_METADATA_EXIF.

Definição de Blob

O blob deve consistir num cabeçalho TIFF completo, primeiro IFD e sub-IFD EXIF, conforme definido pelas especificações EXIF 2.3 e TIFF 6.0. O blob não deve conter quaisquer dados antes do cabeçalho TIFF. O blob não conterá quaisquer dados após o final da 0ª IFD. Por exemplo, não é válido incluir um IFD contendo dados em miniatura.

O diagrama a seguir, copiado da especificação TIFF, ilustra o layout de memória esperado:

Definição de blob EXIF.

Seguem-se requisitos que são consistentes com as especificações EXIF e TIFF, mas que merecem ênfase:

  • A ordem de bytes deve ser: "little endian" ("II") ou "big endian" ("MM").
  • Os ponteiros ("desvios de bytes" na especificação TIFF) devem ser relativos ao início do cabeçalho TIFF.

A seguir estão os requisitos que são mais restritivos do que as especificações EXIF e TIFF:

  • O desvio para a IFD seguinte será 0, ou seja, não são apontadas IFD adicionais.
  • O cabeçalho TIFF e a IFD 0 devem ser contíguos, ou seja, o deslocamento para a IFD 0, conforme armazenado nos bytes 4-7, deve ser 0x8.

Metadados EXIF obrigatórios

A seção abaixo descreve os metadados EXIF que devem ser incluídos no MF_CAPTURE_METADATA_EXIF .

Nome Etiqueta EXIF Descrição
Orientação 274 Orientação da imagem visualizada em termos de linhas e colunas. Consulte as especificações EXIF para obter uma descrição completa
Fazer 271 O fabricante do equipamento de gravação
Modelo 272 O nome do modelo ou o número do modelo do dispositivo
Resolução X 282 O número de pixels por unidade de resolução na direção de largura da imagem (ImageWidth)
ResoluçãoY 283 O número de pixels por unidade de resolução na direção do comprimento da imagem
Unidade de Resolução 296 A unidade para medir XResolution e YResolution
Aplicações informáticas 305 Nome e versão do firmware
Espaço de cores 40961 As informações do espaço de cores são normalmente sRGB.
SubsSecTimeOriginal 37521 Registra frações de segundos associadas à tag DateTimeOriginal
SubSecTimeDigitalizado 37522 Registra frações de segundos associadas à tag DateTimeDigitized
Tempo de exposição 33434 Tempo de exposição em segundos (precisão de 0,001s)
número f 33437 O número F usado para a captura
ISOSpeedRatings 34855 Valor de velocidade ISO conforme definido na ISO 12322, baseado em saturação
DateTimeOriginal 36867 Data e hora em que os dados da imagem original foram gerados
DateTimeDIgitized 36868 A data e a hora em que a imagem é armazenada como dados digitais
Velocidade do obturadorValor 37377 Velocidade do obturador em unidades do Sistema Aditivo de Exposição Fotográfica (APEX)
Valor da abertura 37378 A abertura da lente em unidades APEX
Valor da Compensação de Exposição 37380 Valor de distorção de exposição em unidades APEX
Modo de medição 37383 Modo de medição AE (ver especificação EXIF)
Fonte de luz 37384 O tipo de fonte de luz (ver especificação EXIF)
Flash 37385 Status do flash durante a captura de imagem
FocalLength 37386 A distância focal real da lente
Modo de exposição 41986 Modo de exposição durante a captura
Balanço de Branco 41987 Modo de balanço de branco durante a captura
Razão de Zoom Digital 41988 Relação de zoom digital durante a captura de imagem
Comprimento Focal em Filme de 35mm 41989 Distância focal equivalente a 35 mm
TipoDeCapturaDeCena 41990 Tipo de cena que foi filmada

Metadados opcionais/definidos pelo OEM

O driver da câmera pode incluir quaisquer metadados adicionais na forma de tags EXIF personalizadas, desde que estejam em conformidade com a especificação EXIF e sejam armazenados na 0ª IFD TIFF ou na sub-IFD EXIF.

Requisitos do MakerNote e expectativas de layout binário

O driver da câmera pode incluir informações proprietárias do fabricante na forma de uma nota do fabricante (tag 37500). A nota do fabricante não deve conter nenhum ponteiro para, ou de outra forma confiar em, dados que estão fora da própria nota do criador, incluindo o início do arquivo e a posição do cabeçalho TIFF. Além disso, ele não deve fazer suposições sobre a endianidade do arquivo, conforme especificado no cabeçalho TIFF.

Em geral, o sistema operacional não garante que o layout binário do blob de metadados seja preservado quando ele é gravado no fluxo JPEG de saída. Apenas garante que os metadados são escritos em conformidade com a especificação EXIF. Por exemplo, garante apenas que a nota do fabricante seja copiada como um bloco contíguo e identificada pelo tag, tipo e deslocamento IFD corretos.

Utilização com o codificador WIC JPEG

O uso pretendido do MF_CAPTURE_METADATA_EXIF é com o codificador JPEG do Windows Imaging Component (WIC) fornecido pelo sistema operacional. O pipeline da câmara do Windows usa o codificador JPEG WIC do Windows para consumir os metadados EXIF obtidos de MF_CAPTURE_METADATA_EXIF e combina estes com os dados de pixel da imagem num ficheiro JPEG quando a aplicação não está a capturar um JPEG diretamente da câmara, mas configurou o pipeline para capturar em NV12/YUY2 e ser codificado pelo sistema operativo.

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

O atributo MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID contém o ID para o respetivo quadro na sequência variável de fotos. Este atributo só é definido para uma captura de sequência de fotos variável.

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

MF_CAPTURE_METADATA_FRAME_ILLUMINATION é um atributo das câmaras de infravermelhos que especifica se os quadros estão a usar iluminação infravermelha ativa e deve ser usado em conjunto com FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION. É usado apenas para amostras de IR e não deve estar presente em quadros RGB se a câmera suporta amostras de IR e cores.

O valor deve ser definido como 0xXXXXXXXXXXXXXXX1 se o quadro foi capturado quando a iluminação ativa estava ativada e definido como 0xXXXXXXXXXXXXXXX0 se nenhuma iluminação estava presente ao capturar o quadro.

MF_CAPTURE_METADATA_HISTOGRAM

O atributo MF_CAPTURE_METADATA_HISTOGRAM contém o histograma quando é capturado um quadro pré-visualizado.

As estruturas de dados abaixo descrevem o formato de blob para MF_CAPTURE_METADATA_HISTOGRAM.

typedef struct tagHistogramGrid
{
    ULONG Width;    // Width of the sensor output that histogram is collected from
    ULONG Height;   // Height of the sensor output that histogram is collected from
    RECT Region;    // Absolute coordinates of the region on the sensor output that the histogram is collected for
} HistogramGrid;

typedef struct tagHistogramBlobHeader
{
    ULONG Size;         // Size of the entire histogram blob in bytes
    ULONG Histograms;   // Number of histograms in the blob. Each histogram is identified by a HistogramHeader
} HistogramBlobHeader;

typedef struct tagHistogramHeader
{
    ULONG Size;         // Size of this header + (HistogramDataHeader + histogram data following) * number of channels available
    ULONG Bins;         // Number of bins in the histogram
    ULONG FourCC;       // Color space that the histogram is collected from
    ULONG ChannelMasks; // Masks of the color channels that the histogram is collected for
    HistogramGrid Grid; // Grid that the histogram is collected from
} HistogramHeader;

typedef struct tagHistogramDataHeader
{
    ULONG Size;         // Size in bytes of this header + histogram data following
    ULONG ChannelMask;  // Mask of the color channel for the histogram data
    ULONG Linear;       // 1, if linear; 0 nonlinear
} HistogramDataHeader;

Para o campo ChannelMasks, definiremos as seguintes máscaras de bits para indicar os canais disponíveis no histograma.

#define MF_HISTOGRAM_CHANNEL_Y  0x00000001
#define MF_HISTOGRAM_CHANNEL_R  0x00000002
#define MF_HISTOGRAM_CHANNEL_G  0x00000004
#define MF_HISTOGRAM_CHANNEL_B  0x00000008
#define MF_HISTOGRAM_CHANNEL_Cb 0x00000010
#define MF_HISTOGRAM_CHANNEL_Cr 0x00000020

Observações:

  1. Cada blob pode conter vários histogramas coletados de diferentes regiões ou diferentes espaços de cores do mesmo quadro
  2. Cada histograma no blob é identificado por seu próprio HistogramHeader
  3. Cada histograma tem sua própria região e tamanho de saída do sensor associados. Para histograma de quadro completo, a região corresponderá ao tamanho de saída do sensor especificado em HistogramGrid.
  4. Os dados do histograma para todos os canais disponíveis são agrupados em um histograma. Os dados de histograma para cada canal são identificados por um HistogramDataHeader imediatamente acima dos dados. ChannelMasks indicam quantos e quais canais contêm os dados do histograma, que é a operação OR bit a bit das máscaras de bits MF_HISTOGRAM_CHANNEL_XXX suportadas, conforme definido acima. ChannelMask indica para qual canal os dados se destinam, que é identificado por qualquer uma das MF_HISTOGRAM_CHANNEL_XXX máscaras de bits definidas acima.

A figura abaixo ilustra o layout de um blob de histograma com um histograma de quadro completo somente para Y.

Os dados do histograma são uma matriz de ULONG com cada entrada representando o número de pixels que se enquadram em um conjunto de valores tonais categorizados pelo compartimento. Os dados na matriz devem começar do compartimento 0 ao compartimento N-1, onde N é o número de compartimentos no histograma, ou seja, HistogramBlobHeader.Bins.

A figura abaixo ilustra o layout da seção de dados do histograma.

A figura abaixo ilustra o layout de um blob de histograma com um histograma YRGB de quadro completo com quatro canais.

A figura abaixo ilustra o layout de um blob de histograma com um histograma somente Y seguido por um histograma RGB com três canais.

Para o Threshold, deve ser fornecido, no mínimo, um histograma de quadro completo com canal Y, que deve ser o primeiro histograma no blob de histograma, caso o KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM seja suportado.

Observe que os dados HistogramBlobHeader, HistogramHeader, HistogramDataHeader e Histogram descrevem apenas o formato de blob para o atributo MF_CAPTURE_METADATA_HISTOGRAM. A estrutura do item de metadados para o histograma (KSCAMERA_METADATA_ITEMHEADER + toda a carga útil de metadados do histograma) fica a cargo do driver e deve estar alinhado a 8 bytes.

Controle de metadados de histograma

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM é um ID de propriedade que será usado para controlar os metadados do histograma produzidos pelo driver. Este é um controle de nível de pino apenas para pino de visualização e é definido da seguinte forma:

typedef enum {
    …
#if (NTDDI_VERSION >= NTDDI_WIN8)
    KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM
#endif
} KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY;

Para KSCAMERA_EXTENDEDPROP_HEADER, definiremos os seguintes sinalizadores de bits para gerir os metadados do histograma no driver. O padrão é OFF.

#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_OFF 0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_ON  0x0000000000000001

Esse controle deve ser usado antes do controle KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA para garantir que o buffer de metadados de tamanho adequado seja alocado.

Se definido como HISTOGRAM_OFF, o condutor não deve entregar os metadados do histograma no pino de pré-visualização. O driver não deve incluir o tamanho dos metadados do histograma em seu requisito de tamanho do buffer de metadados.

Se definido como HISTOGRAM_ON, o condutor deve fornecer os metadados do histograma no pino de pré-visualização. O driver deve incluir o tamanho dos metadados do histograma em seu requisito de tamanho do buffer de metadados.

Se o driver não tiver a capacidade de produzir metadados de histograma, o driver não deve implementar esse controle. Se o controlador suportar este controlo, também deve suportar o controlo KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA.

A chamada SET deste controle não tem efeito quando o pino de visualização está em qualquer estado superior ao estado KSSTATE_STOP. O condutor deve rejeitar a chamada SET recebida se a pré-visualização não estiver no estado de paragem e devolver STATUS_INVALID_DEVICE_STATE. Em uma chamada GET, o driver deve retornar as configurações atuais no campo Sinalizadores.

Este é um controle síncrono. Não há recursos definidos para esse controle.

KSCAMERA_EXTENDEDPROP_HEADER

Versão

Deve ser 1.

PinId

Deve ser o Pin ID associado ao Pin de pré-visualização.

Tamanho

Deve ser sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE)

Resultado

Indica os resultados de erro da última operação SET. Se nenhuma operação SET tiver ocorrido, isso deve ser 0.

Capacidade

Deve ser 0.

Bandeiras

Este é um campo de leitura/gravação. Esta pode ser qualquer uma das bandeiras KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX definidas acima.

KSCAMERA_EXTENDEDPROP_VALUE

Não utilizado