Capturar atributos de metadados de estatísticas

A tabela a seguir resume as estatísticas de captura disponíveis IMFAttributes para o recipiente de atributos de metadados MFSampleExtension_CaptureMetaData do MFT0 para visualização, vídeo e captura.

As estatísticas de captura listadas para ainda são obrigatórias para cada foto capturada, a menos que indicado de outra forma. As estatísticas de captura listadas para visualização e vídeo devem ser entregues como o melhor esforço e o driver pode ou não fornecer todas as estatísticas de captura em todos os quadros com base nas considerações de disponibilidade e desempenho.

Nome	Tipo	Pin	Descrição
MF_CAPTURE_METADATA_FOCUSSTATE	UINT32	Versão Prévia	Esse atributo contém o estado de foco atual que pode levar um dos valores a seguir.
MF_CAPTURE_METADATA_SENSORFRAMERATE	UINT64	Versão Prévia	Esse atributo contém a taxa de leitura do sensor medido em hertz quando um quadro de visualização é capturado, que consiste em um valor numerador no 32 bits superior e um valor de denominador no 32 bits inferior.
MF_CAPTURE_METADATA_FACEROIS	Blob	Versão prévia, Vídeo	Esse atributo contém as informações do retângulo facial detectadas pelo driver.
MF_CAPTURE_METADATA_FACEROITIMESTAMPS	Blob	Versão prévia, Vídeo	Esse atributo contém as informações de carimbo de data/hora para os ROIs de rosto identificados em MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS	Blob	Versão prévia, Vídeo	Esse atributo contém o estado de piscar e/ou expressão facial para os ROIs faciais identificados em MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_EXPOSURE_TIME	UINT64	Versão prévia, Ainda	Esse atributo contém o tempo de exposição aplicado em 100 nanossegundos
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION	Blob	Versão prévia, Ainda	Esse atributo contém um sinalizador de etapa de compensação EV e um valor de compensação de EV em unidades da etapa que foi aplicada ao driver quando a foto foi capturada.
MF_CAPTURE_METADATA_ISO_SPEED	UINT32	Versão prévia, Ainda	Esse atributo contém o valor de velocidade ISO aplicado como um inteiro.
MF_CAPTURE_METADATA_LENS_POSITION	UINT32	Versão prévia, Ainda	Esse atributo contém a posição da lente lógica quando o foco foi aplicado à foto capturada. Esse valor não tem uma unidade específica.
MF_CAPTURE_METADATA_SCENE_MODE	UINT64	Ainda	Esse atributo contém o modo de cena aplicado como um sinalizador de UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX .
MF_CAPTURE_METADATA_FLASH	UINT32 (booliano)	Versão prévia, Ainda	Esse atributo contém um valor booliano que contém o estado flash. Um valor de 1 especifica que o flash está ativado e um valor de 0 especifica que o flash está desativado para a foto capturada.
MF_CAPTURE_METADATA_FLASH_POWER	UINT32	Ainda	[Opcional] Esse atributo contém a energia flash aplicada como um valor percentual entre 0 e 100.
MF_CAPTURE_METADATA_WHITEBALANCE	UINT32 (Kelvin)	Versão prévia, Ainda	Esse atributo contém o saldo em branco aplicado como um valor em Kelvin.
MF_CAPTURE_METADATA_ZOOMFACTOR	UINT32 (P16)	Ainda	Esse atributo contém o valor de zoom aplicado e é o mesmo valor que pode ser consultado de KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM em uma chamada GET. O valor deve estar no 16º trimestre.
MF_CAPTURE_METADATA_EXIF	Blob	Ainda	[Opcional] Esse atributo contém metadados EXIF, conforme especificado na seção de definição de blob
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID	UINT32	Ainda	[Opcional] Esse atributo contém a ID de quadro para o quadro correspondente na sequência de fotos variável. Esse atributo é definido apenas para uma captura de sequência de fotos variável.
MF_CAPTURE_METADATA_ISO_GAINS	Blob	Versão Prévia	Esse atributo contém os ganhos analógicos e digitais aplicados ao senor quando o quadro de visualização foi capturado. Isso é sem unidade.
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS	Blob	Versão Prévia	Esse atributo contém os ganhos de saldo em branco aplicados a R, G, B pelo sensor e\ou ISP quando o quadro de visualização foi capturado. Este é um sem unidade.
MF_CAPTURE_METADATA_HISTOGRAM	Blob	Versão Prévia	Esse atributo contém o histograma quando um quadro de visão prévia é capturado.
MF_CAPTURE_METADATA_FRAME_ILLUMINATION	UINT64	Pin de IR usado para Hello	Esse atributo para câmeras IR especifica se os quadros estão usando iluminação de IR ativa e devem ser usados em conjunto com FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION.
Qualquer GUID personalizado	Qualquer tipo de variante		Esse 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 valores a seguir.

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

MF_CAPTURE_METADATA_SENSORFRAMERATE atributo contém a taxa de leitura do sensor medida em hertz quando um quadro de visualização é capturado, que consiste em um valor numerador no 32 bits superior e um valor de denominador no 32 bits inferior.

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS atributo contém as informações do retângulo facial detectadas pelo driver. Por padrão, driver\MFT0 deve fornecer as informações de detecção facial no fluxo de visualização. Se o driver anunciar a funcionalidade em outros fluxos, driver\MFT deverá fornecer as informações de detecção facial nos fluxos correspondentes se o aplicativo habilitar a detecção facial nesses fluxos. Quando a estabilização de vídeo está habilitada no driver, as informações de detecção facial devem ser fornecidas após a estabilização do vídeo. As estruturas de dados abaixo descrevem o formato de blob para MF_CAPTURE_METADATA_FACEROIS. O rosto dominante deve ser o primeiro FaceRectInfo 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 os structs FaceRectinfoBlobHeader e FaceRectInfo descrevem apenas o formato de blob para o atributo MF_CAPTURE_METADATA_FACEROIS. A estrutura do item de metadados para ROIs de detecção facial (KSCAMERA_METADATA_ITEMHEADER + carga de metadados de ROIs faciais) é até o driver e deve estar alinhada a 8 bytes.

Por design, se um fluxo estiver configurado com a detecção facial habilitada e a cena em questão não contiver rostos durante a captura, o driver ainda precisará anexar um atributo "fictício" MF_CAPTURE_METADATA_FACEROIS a cada amostra que não tenha nenhuma informação facial associada a ele. (Um atributo ROI de rosto "fictício" tem o campo Contagem da estrutura FaceRectInfoBlobHeader definido como zero.)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

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

A estrutura de dados abaixo 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 sinalizadores de bit a seguir para indicar qual carimbo de data/hora é válido. O MFT0 deve definir Sinalizadores como MF_METADATATIEMSTAMPS_DEVICE e a hora de QPC apropriada para Dispositivo, se o driver fornecer os metadados de carimbo de data/hora para os ROIs de detecção facial.

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

Observe que o struct MetadataTimeStamps descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_FACEROITIMESTAMPS. A estrutura do item de metadados para o carimbo de data/hora (KSCAMERA_METADATA_ITEMHEADER + carga de metadados de carimbo de data/hora) é até o driver e deve estar alinhada a 8 bytes.

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS atributo 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 dá suporte à detecção de piscar e/ou expressão facial, esse atributo deve ser omitido.

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

Observe que os structs 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 faciais (KSCAMERA_METADATA_ITEMHEADER + carga de metadados de caracterizações faciais) é até o 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 exemplo a seguir define a possível expressão facial que pode ser detectada.  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

Se MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS atributo apresentar, o número e a ordem das entradas FaceCharacterization em seu blob deverão 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ções faciais e um blob de ROIs faciais de quatro rostos com o primeiro nem piscando nem sorrindo, o segundo piscando o olho esquerdo, o terceiro sorrindo e o quarto piscando (ambos os olhos) e sorrindo.

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME atributo contém o tempo de exposição aplicado ao sensor quando o quadro de visualização e\ou foto foi capturado, que é um UINT64 e está em 100ns.

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION atributo contém um sinalizador de etapa de compensação de EV e um valor de Compensação de EV em unidades da etapa aplicada ao sensor quando a versão prévia e o quadro de fotos foram capturados.

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 o struct CapturedMetadataExposturaCompensation descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION. A estrutura do item de metadados para compensação de EV (KSCAMERA_METADATA_ITEMHEADER + carga de metadados de compensação de EV) é até o driver e deve estar alinhada a 8 bytes.

MF_CAPTURE_METADATA_ISO_SPEED

MF_CAPTURE_METADATA_ISO_SPEED atributos contém o valor de velocidade ISO aplicado ao sensor quando a versão prévia e o quadro de fotos foram capturados. Isso é sem unidade.

MF_CAPTURE_METADATA_ISO_GAINS

MF_CAPTURE_METADATA_ISO_GAINS atributo contém os ganhos analógicos e digitais aplicados ao senor quando o quadro de visualização foi capturado. Isso é sem unidade.

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

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

Observe que o struct CapturedMetadataISOGains descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_ISO_GAINS. A estrutura do item de metadados para ganhos de ISO (KSCAMERA_METADATA_ITEMHEADER + ISO ganha carga de metadados) é até o driver e deve estar alinhada a 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 o quadro de fotos foram capturados, o que é sem unidade. Esse é o mesmo valor que pode ser consultado de KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS em uma chamada GET.

MF_CAPTURE_METADATA_SCENE_MODE

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

MF_CAPTURE_METADATA_FLASH

MF_CAPTURE_METADATA_FLASH atributo contém um valor booliano quando o quadro de visualização e\ou foto foi capturado, com 1 significando flash ativado e 0 significando flash off.

MF_CAPTURE_METADATA_FLASH_POWER

MF_CAPTURE_METADATA_FLASH_POWER atributo contém a energia flash aplicada à foto capturada, que é um valor no intervalo de [0, 100]. Esse atributo deverá ser omitido se o driver não der suporte à energia ajustável para flash.

MF_CAPTURE_METADATA_WHITEBALANCE

MF_CAPTURE_METADATA_WHITEBALANCE atributo contém o saldo em branco aplicado ao sensor quando a visualização e o quadro de fotos foram capturados, o que é um valor em Kevin.

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS atributo contém os ganhos de saldo em branco aplicados a R, G, B pelo sensor e\ou ISP quando o quadro de visualização foi capturado. Este é um 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 o struct CapturedMetadataWhiteBalanceGains descreve apenas o formato de blob para o atributo MF_CAPTURE_METADATA_WHITEBALANCE_GAINS. A estrutura do item de metadados para ganhos de saldo em branco (KSCAMERA_METADATA_ITEMHEADER + conteúdo de metadados de ganhos de saldo branco) é até o 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 de KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM em uma chamada GET. Isso deve estar no 16º trimestre.

MF_CAPTURE_METADATA_EXIF

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

Definição de blob

O blob deve consistir em um cabeçalho TIFF completo, 0º IFD e EXIF sub-IFD, conforme definido pelas especificações EXIF 2.3 e TIFF 6.0. O blob não deve conter dados antes do cabeçalho TIFF. O blob não deve conter dados após o final do 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:

A seguir estão os requisitos que são consistentes com as especificações EXIF e TIFF, mas são chamados para dar ênfase:

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

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

• O deslocamento para o próximo IFD deve ser 0, ou seja, nenhum IFD adicional é apontado.
• O cabeçalho TIFF e o 0º IFD devem ser contíguos, ou seja, o deslocamento para o 0º IFD, conforme armazenado em bytes 4-7, deverá ser 0x8.

Metadados EXIF obrigatórios

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

Nome	Marca EXIF	Descrição
Orientation	274	Orientação da imagem exibida em termos de linhas e colunas. Confira especificação EXIF para obter a descrição completa
Faça	271	O fabricante do equipamento de gravação
Modelar	272	O nome do modelo ou o número do modelo do dispositivo
XResolution	282	O número de pixels por unidade de resolução na direção ImageWidth
YResolution	283	O número de pixels por unidade de resolução na direção ImageLength
ResolutionUnit	296	A unidade para medir XResolution e YResolution
Software	305	Nome e versão do firmware
Colorspace	40961	As informações de espaço de cor, normalmente sRGB
SubsSecTimeOriginal	37521	Registra frações de segundos associadas à marca DateTimeOriginal
SubSecTimeDigitized	37522	Registra frações de segundos associadas à marca DateTimeDigitized
ExposureTime	33434	Tempo de exposição em segundos (preciso para 0,001s)
FNumber	33437	O número F usado para captura
ISOSpeedRatings	34855	Valor de velocidade ISO conforme definido em 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 hora em que a imagem é armazenada como dados digitais
SpeedValue do Obturador	37377	Velocidade do obturador em unidades APEX (Sistema Aditivo de Exposição Fotográfica)
Valor de abertura	37378	A abertura da lente em unidades APEX
Valor ExposureBias	37380	Valor de viés de exposição em unidades APEX
MeteringMode	37383	Modo de medição AE (consulte especificação EXIF)
LightSource	37384	O tipo de fonte de luz (consulte especificação EXIF)
Piscando	37385	Status do flash durante a captura de imagem
FocalLength	37386	O comprimento focal real da lente
ExposureMode	41986	Modo de exposição durante a captura
WhiteBalance	41987	Modo de balanceamento de branco durante a captura
DigitalZoomRatio	41988	Taxa de zoom digital durante a captura de imagem
FocalLengthIn35mmFilm	41989	Comprimento focal equivalente de 35 mm
SceneCaptureType	41990	Tipo de cena que foi filmada

Metadados opcionais/definidos por OEM

O driver da câmera pode incluir metadados adicionais na forma de marcas EXIF personalizadas, desde que esteja em conformidade com a especificação EXIF e seja armazenado no 0º TIFF IFD ou no 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 (marca 37500). A observação do criador não deve conter ponteiros para ou depender de dados que estejam fora da própria anotação 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 for gravado no fluxo JPEG de saída. Ele garante apenas que os metadados sejam gravados em conformidade com a especificação EXIF. Por exemplo, ele garante apenas que a nota do criador seja copiada como um bloco contíguo e seja identificada pela marca, tipo e deslocamento IFD corretos.

Uso com o codificador WIC JPEG

O uso pretendido de MF_CAPTURE_METADATA_EXIF é com o codificador JPEG do WIC (Componente de Imagem do Windows) fornecido pelo sistema operacional. Câmera do Windows pipeline usa o codificador JPEG do Windows WIC para consumir metadados EXIF obtidos de MF_CAPTURE_METADATA_EXIF e muxes isso com dados de pixel de imagem em um arquivo JPEG quando o aplicativo não está capturando um JPEG diretamente da câmera, mas configurou o pipeline para capturar para NV12/YUY2 e ser codificado pelo sistema operacional

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID atributo contém a ID do quadro para o quadro correspondente na sequência de fotos da variável. Esse atributo só é definido para uma captura de sequência de fotos variável.

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

MF_CAPTURE_METADATA_FRAME_ILLUMINATION atributo para câmeras de IR especifica se os quadros estão usando iluminação de IR ativa e devem ser usados em conjunto com FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION. Ele só é usado para exemplos de IR e não deve estar presente em quadros RGB se a câmera der suporte a exemplos de IR e cor.

O valor deverá ser definido como 0xXXXXXXXXXXXXXXXXX1 se o quadro tiver sido capturado quando a iluminação ativa estiver ativa e definida como 0xXXXXXXXXXXXXXXXXXXXX se nenhuma iluminação estiver presente ao capturar o quadro.

MF_CAPTURE_METADATA_HISTOGRAM

MF_CAPTURE_METADATA_HISTOGRAM atributo contém o histograma quando o quadro apreview é capturado.

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 máscaras de bits a seguir 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 regiões diferentes ou espaços de cores diferentes 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 o histograma de quadro completo, a região corresponderá ao tamanho de saída do sensor especificado em HistogramGrid.
4. Os dados de 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 estão tendo os dados de histograma, que é o OR bit a bit do MF_HISTOGRAM_CHANNEL_XXX bitmasks com suporte, conforme definido acima. ChannelMask indica para qual canal os dados são, que é identificado por qualquer uma das máscaras de bits MF_HISTOGRAM_CHANNEL_XXX definidas acima.

A figura a seguir ilustra o layout de um blob de histograma com um histograma somente Y de quadro completo.

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

A figura a seguir ilustra o layout da seção de dados de histograma.

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

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

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

Observe que os dados de 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 + todo o conteúdo de metadados de histograma) é até o driver e deve estar alinhada a 8 bytes.

Controle de Metadados de Histograma

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM é uma ID de propriedade que será usada para controlar os metadados de histograma produzidos pelo driver. Esse é um controle de nível de fixação somente para o pin de visualização e é definido como a seguir:

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

Para KSCAMERA_EXTENDEDPROP_HEADER, definiremos os sinalizadores de bit a seguir para controlar os metadados de 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 driver não entregará os metadados de histograma no pino de visualização. O driver não deve incluir o tamanho dos metadados de histograma em seu requisito de tamanho de buffer de metadados.

Se definido como HISTOGRAM_ON, o driver entregará os metadados de histograma no pino de visualização. O driver deve incluir o tamanho dos metadados de histograma em seu requisito de tamanho de buffer de metadados.

Se o driver não tiver a capacidade de produzir metadados de histograma, o driver não deverá implementar esse controle. Se o driver der suporte a esse controle, ele também deverá dar suporte a KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA controle.

A chamada SET desse controle não tem efeito quando o pin de visualização é um estado inany maior que o estado KSSTATE_STOP. O driver rejeitará a chamada SET recebida se a versão prévia não estiver no estado de parada e retornar STATUS_INVALID_DEVICE_STATE. Em uma chamada GET, o driver deve retornar as configurações atuais no campo Sinalizadores.

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

KSCAMERA_EXTENDEDPROP_HEADER

Versão

Deve ser 1.

PinId

Deve ser a ID do Pin associada ao pin de visualização.

Tamanho

Precisa ser sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE)

Result

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

Funcionalidade

Deve ser 0.

Flags

Este é um campo de leitura/gravação. Pode ser qualquer um dos KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX sinalizadores definidos acima.

KSCAMERA_EXTENDEDPROP_VALUE

Não usado