Запись атрибутов метаданных статистики

В таблице ниже приведена сводка доступной статистики захвата IMFAttributes для контейнера атрибутов метаданных MFT0 MFSampleExtension_CaptureMetaData для предварительного просмотра, видео и записи.

Статистика захвата, указанная по-прежнему, является обязательной для каждой фотографии, снятой, если не указано иное. Статистика захвата, указанная для предварительного просмотра и видео, должна быть доставлена как можно лучше, и драйвер может предоставлять или не предоставлять всю статистику захвата для всех кадров в зависимости от доступности и производительности.

Имя	Тип	Pin	Описание
MF_CAPTURE_METADATA_FOCUSSTATE	UINT32	Предварительный просмотр	Этот атрибут содержит текущее состояние фокуса, которое может принимать одно из следующих значений.
MF_CAPTURE_METADATA_SENSORFRAMERATE	UINT64	Предварительный просмотр	Этот атрибут содержит измеряемую скорость считывания датчика в герц при захвате кадра предварительного просмотра, который состоит из значения числителя в верхнем 32 бите и значения знаменателя в нижнем 32 бите.
MF_CAPTURE_METADATA_FACEROIS	BLOB-объект	Предварительный просмотр, видео	Этот атрибут содержит сведения о прямоугольнике лица, обнаруженные драйвером.
MF_CAPTURE_METADATA_FACEROITIMESTAMPS	BLOB-объект	Предварительный просмотр, видео	Этот атрибут содержит сведения о метке времени для лиц с рентабельности инвестиций, определенных в MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS	BLOB-объект	Предварительный просмотр, видео	Этот атрибут содержит состояние мигания и/или выражения лица для конечных показателей, определенных в MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_EXPOSURE_TIME	UINT64	Предварительная версия, по-прежнему	Этот атрибут содержит время экспозиции, применяемое в 100 наносекунд.
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION	BLOB-объект	Предварительная версия, по-прежнему	Этот атрибут содержит флаг шага компенсации ev и значение компенсации ev в единицах шага, примененного к водителю при съемке фотографии.
MF_CAPTURE_METADATA_ISO_SPEED	UINT32	Предварительная версия, по-прежнему	Этот атрибут содержит значение скорости ISO, применяемое в виде целого числа.
MF_CAPTURE_METADATA_LENS_POSITION	UINT32	Предварительная версия, по-прежнему	Этот атрибут содержит логическую позицию объектива при применении фокуса к захваченной фотографии. Это значение не имеет определенной единицы измерения.
MF_CAPTURE_METADATA_SCENE_MODE	UINT64	Еще	Этот атрибут содержит режим сцены, применяемый в качестве флага UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX .
MF_CAPTURE_METADATA_FLASH	UINT32 (логическое значение)	Предварительная версия, по-прежнему	Этот атрибут содержит логическое значение, содержащее состояние флэш-памяти. Значение 1 указывает, что вспышка включена, а значение 0 указывает, что вспышка отключена для фотографии.
MF_CAPTURE_METADATA_FLASH_POWER	UINT32	Еще	[Необязательно] Этот атрибут содержит мощность вспышки, применяемую в виде процентного значения от 0 до 100.
MF_CAPTURE_METADATA_WHITEBALANCE	UINT32 (Кельвин)	Предварительная версия, по-прежнему	Этот атрибут содержит баланс белого, применяемый в качестве значения в Кельвине.
MF_CAPTURE_METADATA_ZOOMFACTOR	UINT32 (Q16)	Еще	Этот атрибут содержит примененное значение масштаба и является тем же значением, которое можно запросить из KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM в вызове GET. Значение должно находиться в квартале 16.
MF_CAPTURE_METADATA_EXIF	BLOB-объект	Еще	[Необязательно] Этот атрибут содержит метаданные EXIF, как указано в разделе определения BLOB-объекта.
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID	UINT32	Еще	[Необязательно] Этот атрибут содержит идентификатор кадра для соответствующего кадра в переменной последовательности фотографий. Этот атрибут задается только для захвата переменной последовательности фотографий.
MF_CAPTURE_METADATA_ISO_GAINS	BLOB-объект	Предварительный просмотр	Этот атрибут содержит аналоговые и цифровые преимущества, применяемые к senor при захвате кадра предварительного просмотра. Это не унитарно.
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS	BLOB-объект	Предварительный просмотр	Этот атрибут содержит преимущества баланса белого, примененные к R, G, B датчиком и/или поставщиком услуг Интернета при захвате кадра предварительного просмотра. Это неунитарный объект.
MF_CAPTURE_METADATA_HISTOGRAM	BLOB-объект	Предварительный просмотр	Этот атрибут содержит гистограмму при захвате кадра предварительного представления.
MF_CAPTURE_METADATA_FRAME_ILLUMINATION	UINT64	Пин-код IR, используемый для Hello	Этот атрибут для камер IR указывает, используются ли кадры активной иллюминацией IR, и его следует использовать в сочетании с FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION.
Любой настраиваемый GUID	Любой тип варианта		Этот атрибут содержит пользовательские данные, связанные с пользовательским GUID.

MF_CAPTURE_METADATA_FOCUSSTATE

MF_CAPTURE_METADATA_FOCUSSTATE атрибут содержит текущее состояние фокуса, которое может принимать одно из следующих значений.

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 атрибут содержит измеряемую скорость считывания датчика в герц при захвате кадра предварительного просмотра, который состоит из значения числителя в верхнем 32 бите и значения знаменателя в нижнем 32 бите.

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS атрибут содержит сведения о прямоугольнике лица, обнаруженные драйвером. По умолчанию driver\MFT0 должен предоставлять сведения о лицах в потоке предварительного просмотра. Если драйвер объявляет возможность в других потоках, driver\MFT должен предоставить сведения о лицах в соответствующих потоках, если приложение включает обнаружение лиц в этих потоках. Если в драйвере включена стабилизация видео, после стабилизации видео следует указать сведения о лицах. Приведенные ниже структуры данных описывают формат больших двоичных объектов для MF_CAPTURE_METADATA_FACEROIS. Доминантное лицо должно быть первым FaceRectInfo в большом двоичном объекте.

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;

Обратите внимание, что структуры FaceRectinfoBlobHeader и FaceRectInfo описывают только формат больших двоичных объектов для атрибута MF_CAPTURE_METADATA_FACEROIS. Структура элементов метаданных для рентабельности инвестиций лиц (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных рентабельности лиц) определяется драйвером и должна быть выровнена по 8 байтам.

Если поток настроен с включенным обнаружением лиц, а соответствующая сцена не содержит лиц во время захвата, драйвер по-прежнему должен прикрепить фиктивный атрибут MF_CAPTURE_METADATA_FACEROIS к каждому образцу, с которым не связана информация о лицах. (Для атрибута "фиктивный" окупаемости лиц поле Count структуры FaceRectInfoBlobHeader установлено равным нулю.)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

MF_CAPTURE_METADATA_FACEROITIMESTAMPS атрибут содержит сведения о метке времени для параметров рентабельности инвестиций лиц, определенных в MF_CAPTURE_METADATA_FACEROIS. Для устройства, которое не может предоставить метку времени для лицевой рентабельности, этот атрибут следует опустить.

В приведенной ниже структуре данных описывается формат больших двоичных объектов для 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;

Для поля Флаги мы определим следующие битовые флаги, чтобы указать, какая метка времени допустима. MFT0 должен задать для параметра Flags значение MF_METADATATIEMSTAMPS_DEVICE и соответствующее время QPC для устройства, если драйвер предоставляет метаданные метки времени для рентабельности инвестиций лиц.

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

Обратите внимание, что в структуре MetadataTimeStamps описывается только формат больших двоичных объектов для атрибута MF_CAPTURE_METADATA_FACEROITIMESTAMPS. Структура элементов метаданных для метки времени (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных метки времени) определяется драйвером и должна быть выровнена по 8 байтам.

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS атрибут содержит состояние мигания и/или выражения лица для рентабельности инвестиций лиц, определенных в MF_CAPTURE_METADATA_FACEROIS.  Для устройства, которое не поддерживает распознавание мигания или выражения лица, этот атрибут следует опустить.

В приведенной ниже структуре данных описывается формат больших двоичных объектов для MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS.

Обратите внимание, что структуры FaceCharacterizationBlobHeader и FaceCharacterization описывают только формат больших двоичных объектов для атрибута MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS. Структура элементов метаданных для характеристик лиц (полезные данные метаданных KSCAMERA_METADATA_ITEMHEADER + характеристики лиц) соответствует драйверу и должна быть выровнена по 8 байтам.

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;

Ниже определяется возможное выражение лица, которое можно обнаружить.  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

Если MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS атрибут представлен, число и порядок записей FaceCharacterization в большом двоичном объекте должны совпадать с числом и порядком записей FaceRectInfo в большом двоичном объекте MF_CAPTURE_METADATA_FACEROIS.   Каждая запись FaceCharacterization представляет мигание и/или состояние выражения лица в соответствующей записи FaceRectInfo по тому же индексу.

На рисунке ниже показаны макеты большого двоичного объекта характеристики лица и большого двоичного объекта распознавания лиц с четырьмя лицами: первое не мигает и не улыбается, второе мигает левым глазом, третье улыбается, а четвертое — мигает (оба глаза) и улыбается.

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME атрибут содержит время экспозиции, примененное к датчику при предварительном просмотре и/или фоторамке, которая является UINT64 и составляет 100 нс.

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION атрибут содержит флаг шага компенсации ev и значение компенсации EV в единицах шага, примененного к датчику при предварительном просмотре и/или фоторамке.

В приведенной ниже структуре данных описывается формат больших двоичных объектов для 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;

Обратите внимание, что в структуре CapturedMetadata ExposureCompensation описывается только формат большого двоичного объекта для атрибута MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION. Структура элементов метаданных для компенсации ev (KSCAMERA_METADATA_ITEMHEADER + метаданные компенсации ev) определяется драйвером и должна быть выровнена по 8 байтам.

MF_CAPTURE_METADATA_ISO_SPEED

MF_CAPTURE_METADATA_ISO_SPEED атрибуты содержат значение скорости ISO, применяемое к датчику при предварительном просмотре и/или фотокадре. Это не унитарно.

MF_CAPTURE_METADATA_ISO_GAINS

MF_CAPTURE_METADATA_ISO_GAINS атрибут содержит аналоговые и цифровые преимущества, применяемые к senor при захвате кадра предварительного просмотра. Это не унитарно.

В приведенной ниже структуре данных описывается формат больших двоичных объектов для MF_CAPTURE_METADATA_ISO_GAINS.

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

Обратите внимание, что в структуре CapturedMetadataISOGains описывается только формат больших двоичных объектов для атрибута MF_CAPTURE_METADATA_ISO_GAINS. Структура элементов метаданных для прибыли ISO (KSCAMERA_METADATA_ITEMHEADER + полезные данные метаданных получения ISO) определяется драйвером и должна быть выровнена по 8 байтам.

MF_CAPTURE_METADATA_LENS_POSITION

MF_CAPTURE_METADATA_LENS_POSITION атрибут содержит логическую позицию объектива при предварительном просмотре и/или фоторамке, которая является неунитарной. Это то же значение, которое можно запросить из KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS в вызове GET.

MF_CAPTURE_METADATA_SCENE_MODE

MF_CAPTURE_METADATA_SCENE_MODE атрибут содержит режим сцены, применяемый к фотографии, которая является 64-разрядным флагом KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX.

MF_CAPTURE_METADATA_FLASH

MF_CAPTURE_METADATA_FLASH атрибут содержит логическое значение при захвате предварительного просмотра и(или) кадра с 1 означает включение вспышки и 0 — вспышка.

MF_CAPTURE_METADATA_FLASH_POWER

MF_CAPTURE_METADATA_FLASH_POWER атрибут содержит мощность вспышки, применяемую к фотографии, которая является значением в диапазоне [0, 100]. Этот атрибут следует опустить, если драйвер не поддерживает регулировку питания для флэш-памяти.

MF_CAPTURE_METADATA_WHITEBALANCE

MF_CAPTURE_METADATA_WHITEBALANCE атрибут содержит баланс белого, примененный к датчику при предварительном просмотре и(или) фотокадре, который является значением в Кевине.

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS атрибут содержит преимущества баланса белого, примененные к R, G, B датчиком и/или поставщиком услуг Интернета при захвате кадра предварительного просмотра. Это неунитарный объект.

В приведенной ниже структуре данных описывается формат больших двоичных объектов для MF_CAPTURE_METADATA_WHITEBALANCE_GAINS.

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

Обратите внимание, что в структуре CapturedMetadataWhiteBalanceGains описывается только формат больших двоичных объектов для атрибута MF_CAPTURE_METADATA_WHITEBALANCE_GAINS. Структура элементов метаданных для выигрыша баланса белого (KSCAMERA_METADATA_ITEMHEADER + полезные данные для получения метаданных баланса белого) определяется драйвером и должна быть выровнена по 8 байтам.

MF_CAPTURE_METADATA_ZOOMFACTOR

MF_CAPTURE_METADATA_ZOOMFACTOR атрибут содержит значение масштаба, примененное к фотографии, которое является тем же значением, которое можно запросить из KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM в вызове GET. Это должно быть в квартале 16.

MF_CAPTURE_METADATA_EXIF

MF_CAPTURE_METADATA_EXIF содержит метаданные EXIF, как указано в разделе 3.1 (определение BLOB-объекта). MFT0 извлекает необработанные метаданные EXIF, которые идентифицируются как элемент пользовательских метаданных (MetadataId >= MetadataId_Custom_Start), из буфера MF_CAPTURE_METADATA_FRAME_RAWSTREAM, предоставленного драйвером. Затем MFT0 преобразует необработанные данные в атрибут MF_CAPTURE_METADATA_EXIF.

Определение BLOB-объекта

Большой двоичный объект должен состоять из полного заголовка TIFF, 0th IFD и EXIF sub-IFD, как определено в спецификациях EXIF 2.3 и TIFF 6.0. Большой двоичный объект не должен содержать никаких данных до заголовка TIFF. Большой двоичный объект не должен содержать никаких данных после окончания 0-го IFD. Например, недопустимо включать IFD, содержащий данные эскизов.

На следующей схеме, скопированной из спецификации TIFF, показан ожидаемый макет памяти:

Ниже приведены требования, которые соответствуют спецификациям EXIF и TIFF, но выделены для акцента:

• Порядок байтов должен быть либо маленьким эндианом ("II") или большим эндианом("ММ").
• Указатели ("смещения байтов" в спецификации TIFF) должны быть относительно начала заголовка TIFF.

Ниже приведены требования, которые являются более строгими, чем спецификации EXIF и TIFF.

• Смещение к следующему IFD должно быть 0, т. е. дополнительные МД не указываются.
• Заголовок TIFF и 0-й IFD должны быть смежными, т. е. смещение до 0-го IFD, сохраненного в байтах 4–7, должно быть 0x8.

Обязательные метаданные EXIF

В разделе ниже описаны метаданные EXIF, которые должны быть включены в MF_CAPTURE_METADATA_EXIF .

Имя	Тег EXIF	Описание
Ориентация	274	Ориентация изображения, просматриваемая с точки зрения строк и столбцов. Полное описание см. в спецификации EXIF.
Убедитесь,	271	Изготовитель записывающей техники
Моделирование	272	Имя модели или номер модели устройства
XResolution	282	Число пикселей на единицу разрешения в направлении ImageWidth
YResolution	283	Число пикселей на единицу разрешения в направлении ImageLength
ResolutionUnit	296	Единица измерения XResolution и YResolution
Программное обеспечение	305	Имя и версия встроенного ПО
ColorSpace	40961	Сведения о цветовом пространстве, как правило, sRGB
SubsSecTimeOriginal	37521	Записывает доли секунд, связанные с тегом DateTimeOriginal
SubSecTimeDigitized	37522	Записывает доли секунд, связанные с тегом DateTimeDigitized
ExposureTime	33434	Время экспозиции в секундах (точная до 0,001 с)
FNumber	33437	Номер F, используемый для записи
ISOSpeedRatings	34855	Значение скорости ISO, определенное в ISO 12322, на основе насыщенности
DateTimeOriginal	36867	Дата и время создания исходных данных изображения
DateTimeDIgitized	36868	Дата и время сохранения образа в виде цифровых данных
Shutter SpeedValue	37377	Скорость затвора в единицах аддитивной системы фотографической экспозиции (APEX)
Значение диафрагмы	37378	Диафрагма объектива в единицах APEX
Значение ExposureBias	37380	Значение смещения экспозиции в единицах APEX
MeteringMode	37383	Режим измерения AE (см. спецификацию EXIF)
LightSource	37384	Тип источника света (см. спецификацию EXIF)
Мигание	37385	Состояние вспышки во время захвата изображения
FocalLength	37386	Фактическое фокусное расстояние объектива
ExposureMode	41986	Режим экспозиции во время захвата
WhiteBalance	41987	Режим баланса белого во время захвата
DigitalZoomRatio	41988	Коэффициент цифрового масштабирования во время захвата изображения
FocalLengthIn35mmFilm	41989	35 мм эквивалентная фокусная длина
SceneCaptureType	41990	Тип сцены, которая была снята

Необязательные метаданные или метаданные, определяемые OEM

Драйвер камеры может включать любые дополнительные метаданные в виде пользовательских тегов EXIF, если он соответствует спецификации EXIF и хранится в 0-м TIFF IFD или EXIF sub-IFD.

Требования MakerNote и ожидания двоичного макета

Драйвер камеры может содержать сведения о изготовителе в виде заметки изготовителя (тег 37500). Заметка о создателе не должна содержать указателей на данные, которые находятся за пределами самой заметки создателя, включая начало файла и положение заголовка TIFF. Кроме того, он не должен делать предположений о endianness файла, как указано в заголовке TIFF.

Как правило, операционная система не гарантирует, что двоичный макет большого двоичного объекта метаданных сохраняется при записи в выходной поток JPEG. Это гарантирует только то, что метаданные будут записаны в соответствии со спецификацией EXIF. Например, это гарантирует, что заметка создателя будет скопирована как непрерывный блок и будет определена правильным тегом IFD, типом и смещением.

Использование с кодировщиком WIC JPEG

Предполагаемое использование MF_CAPTURE_METADATA_EXIF осуществляется с помощью предоставленного ОС кодировщика JPEG компонента образов Windows (WIC). Камера Windows конвейер использует кодировщик Windows WIC JPEG для использования метаданных EXIF, полученных из MF_CAPTURE_METADATA_EXIF, и сопоставляет их с данными пикселей изображения в JPEG-файл, если приложение не захватывает JPEG непосредственно с камеры, а настраивает конвейер для записи в NV12/YUY2 и кодируется ОС

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID атрибут содержит идентификатор кадра для соответствующего кадра в переменной последовательности фотографий. Этот атрибут задается только для захвата переменной последовательности фотографий.

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

MF_CAPTURE_METADATA_FRAME_ILLUMINATION атрибут для камер IR указывает, используются ли кадры активной подсветкой IR и должны использоваться в сочетании с FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION. Он используется только для примеров IR и не должен присутствовать на RGB-кадрах, если камера поддерживает как ir, так и цветовые образцы.

Значение должно иметь значение 0xXXXXXXXXXXXXXXXXXXX1, если кадр был захвачен при активном освещении, и иметь значение 0xXXXXXXXXXXXX, если при захвате кадра не было освещенности.

MF_CAPTURE_METADATA_HISTOGRAM

MF_CAPTURE_METADATA_HISTOGRAM атрибут содержит гистограмму при захвате предварительного кадра.

Приведенные ниже структуры данных описывают формат больших двоичных объектов для 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;

Для поля ChannelMasks мы определим следующие битовые маски, чтобы указать доступные каналы в гистограмме.

#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

Примечания.

1. Каждый большой двоичный объект может содержать несколько гистограмм, собранных из разных регионов или разных цветовых пространств одного кадра.
2. Каждая гистограмма в большом двоичном объекте идентифицируется с помощью собственной histogramHeader
3. Каждая гистограмма имеет собственную область и связанный размер выходных данных датчика. Для полнокадровой гистограммы область будет соответствовать размеру выходных данных датчика, указанному в histogramGrid.
4. Данные гистограммы для всех доступных каналов группируются в одну гистограмму. Данные гистограммы для каждого канала идентифицируются histogramDataHeader непосредственно над данными. ChannelMasks указывает, сколько и какие каналы содержат данные гистограммы, то есть битовое ИЛИ поддерживаемого MF_HISTOGRAM_CHANNEL_XXX битовых масок, как определено выше. ChannelMask указывает, для какого канала являются данные, который идентифицируется любым из MF_HISTOGRAM_CHANNEL_XXX битовых систем, определенных выше.

На рисунке ниже показан макет большого двоичного объекта гистограммы с полнокадровой гистограммой только по Y.

Данные гистограммы — это массив ULONG с каждой записью, представляющей количество пикселей, подпадающих под набор тональных значений, классифицированных по ячейке. Данные в массиве должны начинаться с bin 0 в ячейку N-1, где N — это количество ячеек в гистограмме, т. е. HistogramBlobHeader.Bins.

На рисунке ниже показан макет раздела данных гистограммы.

На рисунке ниже показан макет большого двоичного объекта гистограммы с полнокадровой гистограммой YRGB с четырьмя каналами.

На рисунке ниже показан макет большого двоичного объекта гистограммы с гистограммой только по Y, за которой следует гистограмма RGB с тремя каналами.

Для порогового значения необходимо предоставить как минимум полную гистограмму с каналом Y, которая должна быть первой гистограммой в большом двоичном объекте гистограммы, если поддерживается KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM.

Обратите внимание, что данные HistogramBlobHeader, HistogramHeader, HistogramDataHeader и Histogram описывают только формат большого двоичного объекта для атрибута MF_CAPTURE_METADATA_HISTOGRAM. Структура элементов метаданных для гистограммы (KSCAMERA_METADATA_ITEMHEADER + все полезные данные метаданных гистограммы) соответствует драйверу и должна быть выровнена по 8 байтам.

Элемент управления метаданными гистограммы

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM — это идентификатор свойства, который будет использоваться для управления метаданными гистограммы, созданными драйвером. Это элемент управления уровня закрепления только для предварительного просмотра пин-кода и определяется следующим образом:

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

Для KSCAMERA_EXTENDEDPROP_HEADER мы определим следующие битовые флаги для управления метаданными гистограммы в драйвере. Значение по умолчанию — OFF.

#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_OFF 0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_ON  0x0000000000000001

Этот элемент управления необходимо использовать перед элементом управления KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA, чтобы обеспечить выделение буфера метаданных соответствующего размера.

Если задано значение HISTOGRAM_OFF, драйвер не должен доставлять метаданные гистограммы при предварительном просмотре. Драйвер не должен включать размер метаданных гистограммы в требование к размеру буфера метаданных.

Если задано значение HISTOGRAM_ON, драйвер должен доставить метаданные гистограммы в предварительной версии. Драйвер должен включать размер метаданных гистограммы в требование к размеру буфера метаданных.

Если драйвер не имеет возможности создавать метаданные гистограммы, драйвер не должен реализовывать этот элемент управления. Если драйвер поддерживает этот элемент управления, он также должен поддерживать элемент управления KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA.

Вызов SET этого элемента управления не оказывает никакого влияния, если контакт предварительного просмотра не находится в состоянии выше, чем состояние KSSTATE_STOP. Драйвер должен отклонить полученный вызов SET, если предварительная версия не находится в состоянии остановки и возвращает STATUS_INVALID_DEVICE_STATE. В вызове GET драйвер должен вернуть текущие параметры в поле Флаги.

Это синхронный элемент управления. Для этого элемента управления не определены возможности.

KSCAMERA_EXTENDEDPROP_HEADER

Версия

Должен иметь значение 1.

PinId

Должен быть идентификатором пин-кода, связанным с контактом предварительного просмотра.

Размер

Должен содержать значение sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE).

Результат

Указывает результаты ошибки последней операции SET. Если операция SET не выполнена, это должно быть 0.

Функция

Должно быть равно 0.

Флаги

Это поле для чтения и записи. Это может быть любой из флагов, KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX определенных выше.

KSCAMERA_EXTENDEDPROP_VALUE

Не используется