Руководство пользователя FLM

Приложение **Frame Latency Meter (FLM)** позволяет измерять задержку «от клика до фотона» (нажатие кнопки мыши $\rightarrow$ вспышка выстрела) и, по умолчанию, задержку «от прицеливания до фотона» (движение мыши $\rightarrow$ изменение сцены). FLM замеряет время с момента отправки сообщения о движении мыши до момента изменения изображения на экране.

### Преимущества
* FLM оценивает эффективную частоту кадров (framerate), чего не могут делать другие устройства.
* FLM имеет открытый исходный код!

### Использование движения сцены мышью (Настройка по умолчанию)
* Для измерения задержки не нужны патроны, поэтому они никогда не закончатся — вы можете быстро проводить столько измерений, сколько пожелаете. В результате приложение может работать автономно, собирая неограниченное количество образцов, что обеспечивает гораздо более высокую точность.
* Измерение не зависит от анимации вспышки дульного среза, которая (в зависимости от разработчика) может отображаться с задержкой, что приводит к неточным результатам.
* Вы можете измерять задержку в играх, где нет стрельбы из огнестрельного оружия (например, стрельба из лука или исследование мира).

### Использование клика мыши и вспышки выстрела (Опционально)
* Предусмотрена возможность переключения измерений в режим «клика мыши» во время работы через графический пользовательский интерфейс (GUI).

### Выбор подходящей сцены для измерения
* Для измерения задержки FLM будет перемещать мышь вправо-влево на небольшое расстояние.
* Чтобы FLM точно определил изменение изображения, рекомендуется поместить **область захвата (capture region)** рядом с контрастным вертикальным краем объекта.
* Выберите область, в которой наблюдается значительное изменение пикселей между кадрами при движении мыши влево и вправо.
* Убедитесь, что область захвата более-менее статична — таким образом, единственной причиной изменения изображения будет движение мыши.

### Командная строка
Чтобы просмотреть доступные опции командной строки, запустите:
`flm.exe -help`

Будут отображены различные параметры, которые можно использовать для переопределения автонастроек захвата кадров, а также инструкции по запуску приложения:
* `-AMF`: захват кадров с использованием кодека AMF (опция по умолчанию, работает только для GPU AMD).
* `-DXGI`: захват кадров с использованием кодека захвата рабочего стола (работает на любом GPU, подключенном к основному дисплею).

Запуск `flm.exe` без параметров приведет к автоматическому определению вендора системы и GPU, после чего будет выбран лучший кодек для захвата. Если вы хотите изменить это, укажите кодек в командной строке.
*Пример:* `flm.exe -DXGI` (будет использован кодек захвата рабочего стола, поддерживаемый любым GPU с DX11).

### Как провести тест с использованием движения мыши
**Шаг 1: Настройте основной монитор, на котором запущена игра.**
* Установите режим FreeSync или подходящую частоту обновления (для начала попробуйте 60 Гц).

**Шаг 2: Запустите `flm.exe` от имени администратора.**
* Чтобы увидеть ограничивающую рамку области захвата, нажмите и удерживайте клавишу **правый Alt**. Если вы используете несколько мониторов и кодек захвата рабочего стола, убедитесь, что окно консоли находится в поле зрения основного дисплея.
* Проверьте, чтобы цвет рамки оставался **желтым** — это означает, что захват кадров работает. Если рамка стала **красной**, значит, выбранный кодек не может захватывать кадры и измерение задержки будет невозможно.

**Шаг 3: Запустите игру.**
* Отрегулируйте положение сцены в игре так, чтобы область захвата FLM находилась там, где изображение меняется с темного на светлое при горизонтальном движении мыши.

**Шаг 4: Нажмите комбинацию клавиш для начала измерений (по умолчанию ALT+T).**
* Подождите несколько секунд, пока процесс запустится. Вы увидите, как курсор мыши быстро перемещается влево и вправо, пока приложение записывает данные. В некоторых играх может потребоваться зажать клавишу мыши для активации движения. Если движение слишком малое, измените положение сцены или настройте параметр `MouseHorizontalStep` в файле `flm.ini`.
* Если измерения не отображаются или идут медленно, остановите их (Alt+T) и попробуйте другое место в сцене с лучшим контрастом.
* По умолчанию FLM работает в режиме «RUN», выводя средние значения задержки в мс (`latency[ms]`) и в кадрах (`latency[frames]`) за 16 последовательных измерений. Режим можно изменить в диалоговом окне настроек или в INI-файле.
* *Формат вывода:* `fps = xxx.x | ................ | latency = xxx.x | frames = x.xxx`
* Если значения не меняются или меняются медленно — остановите тест, смените локацию в игре и повторите попытку.

**Шаг 5: Остановите измерения (Alt+T) и изучите результаты.**

---

### Интерфейс (GUI)
Графический интерфейс открывается при **правом клике мыши по окну консоли FLM**.
1. Окно будет отображаться, пока вы его не закроете, не нажмете правую кнопку мыши снова, клавишу ESC или не начнете измерения.
2. Иногда оно может оказаться за окном консоли.

### Как провести тест с использованием клика мыши
Для этого активируйте соответствующую опцию в GUI (правый клик по консоли). Все изменения в интерфейсе вступают в силу немедленно при старте измерений. Новые настройки сохраняются только при изменении области захвата или нажатии кнопки **«Save settings to INI»**.

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

**Дополнительно:**
* **Auto (чекбокс):** Включает автоматическую настройку смещения (bias). FLM внутренне рассчитает частоту кадров и скорректирует задержку для данной позиции рамки захвата. Значение Bias будет сохранено в `flm.ini` при закрытии программы (в соответствующем разделе `MonitorCalibration_`).
* **Область захвата:** Рамку можно переместить туда, где в игре происходит вспышка выстрела. Используйте кнопку **«Set Capture Region»**, переместите и измените размер рамки мышью, затем снова нажмите «Set Capture Region» или «Close». Это обновит параметры `StartX`, `StartY`, `CaptureWidth` и `CaptureHeight` в файле `flm.ini`.

### Настройка вывода консоли
Чтобы получить детальный отчет по каждому кадру, измените параметр `PrintLevel` в INI-файле на **«Operational Mode»**. В этом случае будет выводиться значение для каждого отдельного замера:
* `fps` — средняя частота кадров.
* `... значения` — задержки [мс] для индивидуальных измерений (количество значений задается параметром `MeasurementsPerLine`).
* `latency` — средняя задержка [мс] за строку.
* `frames` — средняя задержка [кадры] за строку.

Если установить `PrintLevel = 2` (**Debug Mode**), запись в CSV-файл будет отключена, а в консоль будет непрерывно выводиться подробный список измерений для отладки кодека.

### Сохранение результатов
По умолчанию FLM сохраняет данные в CSV-файл, путь к которому указан в параметре `OutputFile` файла `flm.ini`. Файл перезаписывается при каждом новом запуске измерений.

---

### Настройка и устранение неполадок

**Проверка работоспособности захвата:**
* **Отображение рамки:** Включите `ShowBoundingBox = true` в `flm.ini`. В оконном режиме игры нажмите правый Alt:
* **Желтый**: Захват работает.
* **Красный**: Захват не удался (попробуйте перезапустить или сменить кодек на -DXGI / -AMF).
* **Белый**: Обновление захвата рабочего стола не работает.

**Сохранение кадра в BMP:**
Нажмите **RSHIFT + Enter**. В консоли появится сообщение «image file saved». Файл `captured_frame.bmp` будет сохранен в папке с программой. Если файл пустой — захват не работает.

**Проверка производительности захвата:**
Нажмите **LSHIFT + Enter**, чтобы начать сохранение последовательности кадров в BMP-файлы. Если вы используете счетчик кадров в игре, проверьте, что номера кадров в сохраненных файлах идут по порядку (повторы допустимы, пропуски или нарушение порядка означают, что кодек слишком медленный для данной системы).

### Технические детали (Порог срабатывания)
FLM рассчитывает абсолютную разницу между кадрами и использует множитель порога (**ThresholdCoefficient**) для определения момента изменения картинки.
* По умолчанию: `ThresholdCoefficientMove = 2.0` (для движения), `ThresholdCoefficientClick = 1.0` (для клика).

### BIAS (Калибровка монитора)
Смещение (Bias) используется для компенсации задержек системы и монитора с фиксированной частотой обновления.
**Ручная калибровка:**
1. Установите значение `MonitorCalibration_...` в 0 в INI-файле.
2. Запустите FLM в режиме «клика мыши».
3. Настройте область захвата так, чтобы она совпадала с областью вашего аппаратного устройства замера (например, монитор NVIDIA Reflex).
4. Сравните значение на аппаратном устройстве и в FLM. Разница между ними и будет вашим значением смещения (Bias), которое нужно вписать в `MonitorCalibration_xxx`.

**Программные vs Аппаратные измерения:**
Аппаратные замеры учитывают время от физического нажатия до изменения пикселя. Программные (FLM) замеряют время от события в ОС до изменения буфера кадра, не учитывая время передачи кадра на монитор и задержку самого железа мыши. Эта сумма разниц и называется **Bias**.

**Auto Bias:**
Если `AutoBias = true` в INI или GUI, FLM сам определит константу смещения. В этом случае ручные настройки `MonitorCalibration_...` будут игнорироваться.

---

### Настройки клавиатуры
* **Alt+T**: Старт/Стоп измерений.
* **Alt+Q**: Выход из приложения.
Эти клавиши можно изменить в `flm.ini` (`MeasurementKeys` и `AppExitKeys`). Допускается комбинация до 3 клавиш (например, `CTRL+LSHIFT+T`).

### Рекомендации по области захвата
Используйте как можно меньшие области захвата. Чем больше область, тем больше ресурсов CPU требуется для обработки разницы между кадрами, что может замедлить работу.

### Окно консоли
Рекомендуется сворачивать окно консоли во время тестов или установить `AppWindowTopMost = false` в INI-файле, чтобы окно находилось за игрой. Убедитесь, что игра находится в фокусе при проведении замеров.

### Известные проблемы и ограничения
* При очень высокой частоте кадров (FPS) результаты FLM могут быть выше, чем у аппаратных устройств.
* Некоторые игры блокируют захват экрана через DXGI.
* Стандартные настройки порога срабатывания (`ThresholdCoefficient`) могут не сработать в некоторых сценах — попробуйте изменить их в INI-файле.
* Кодек DXGI должен работать на основном дисплее, иначе захват будет слишком медленным.
* Расчеты SAD выполняются на CPU и могут быть медленными на слабых ПК.
* **FLM не работает через удаленный рабочий стол (Remote Desktop).**