CC BY
966 East European Scientific Journal #10(74), 2021 through the existing GPRS and BT channels to a remote receiving point (PC).
The total consumption of the MM circuit (without HE) is not more than 20 mA, and the total consumption of the entire device in the data transmission mode through the communication channel is 250 mA. Power MVS can be carried out as from AB voltage of 7 ... 24 V, and from AC 220V (50 Hz) using a network adapter (NA) with a voltage of 12 V.
CONCLUSION
On the basis of MM, a new magnetometric device was created - fluxgate MVS, which allows for measurements and scientific research, both in the MO conditions and in the conditions of the expedition. At the same time, the use of DI allows you to set in the process of research FS arbitrarily, measure the components of the MIV and calculate its module (Br).
The created MM on the basis of a three-component FS has sufficiently high accuracy characteristics and low power consumption, which allows it to be used as a universal element for many geophysical measuring systems. For example, the scheme and design of the MM was used in the development of marine magnetometers and gradientometers [5-7], as well as a search field device [8-10]. The results of full-scale tests of these devices in the process of conducting scientific expeditions and prospecting operations showed satisfactory results.
LITERATURE
1. Lyubimov V.V., Zverev A.S., Sumenko K.G. Ferrosonde search towed magnetometer-gradientometer: development experience // Eurasian Scientific Association. M., 2019. No.1 (47). S.416-420.
УДК 004.457
2. Magnetic Field Sensor FLC3-70. Stefan Mayer Instruments GmbH & Co. KG, Wallstr. 7 D-46535 Dinslaken, Germany. (http://www.stefan-mayer.com)
3. Analog Devices. High Accuracy, Dual-Axis Digital Inclinometer and Accelerometer Data Sheet ADIS16209
(https://www.analog.com/media/en/technical-documentation/data-sheets/ADIS16209.pdf)
4. Lyubimov V.V. To the question of improving the accuracy of magnetic field measurements: Experience of thermostating magnetometer sensors // Prydneprovskyi scientific bulletin / Geophysics. G. Dnepr: Nauka i okrazovats', 2017. Volume 3. No.4. S.84-93.
5. Zverev A.S., Lyubimov V.V. Marine component gradientometer // Eurasian Union of Scientists (ЕСУ). М., 2019. No.10 (67) 5 part. S.4-7.
6. Zverev A.S., Lyubimov V.V. Gradientometer for hydromagnetic surveying // Sensors and systems. M.: «SENSIDAT-PLUS», 2019. No.12 (242). S.46-50.
7. Lyubimov V.V. Marine gradientometer based on one towed gondola // Devices. M., 2020. No.2 (236). S.39-43.
8. Lyubimov V.V. "Ferrosonde rake" - a device for searching for magnetic objects and geomagnetic researches // Eurasian Scientific Association. M., 2020. No.7 (65). S.120-123.
9. Lyubimov V.V. Gradientometers for the search of local ferromagnetic objects // Eurasian Union of Scientists (ESU). M., 2020. No.12 (81) 2 part. S.38-44.
10. Lyubimov V.V. Component magnetometer-gradientometer // Devices. M., 2021. No.4 (250). S.17-21.
Pushkar A.S.
2nd year master's student National Technical University of Ukraine "Igor Sikorsky Kyiv Polytechnic Institute "
DEVELOPMENT OF DIRECT3D 12 GRAPHICS API BINDINGS LIBRARY FOR RUST
Пушкарь А. С.
агистрант 2-го курса Национальный технический университет Украины «Киевский политехнический институт имени Игоря Сикорского»
РАЗРАБОТКА БИБЛИОТЕКИ ПРИВЯЗОК К ГРАФИЧЕСКОМУ ПРОГРАММНОМУ ИНТЕРФЕЙСУ DIRECT3D 12 ДЛЯ ЯЗЫКА RUST
Summary: Nowadays C++ and, to a lesser extent, C programming languages vastly dominate the area of graphics programming. As a result, modern graphics APIs are tailored for interacting with these languages only, which makes development in other programming languages difficult or impossible. The article examines the development of Direct3D 12 API bindings for Rust, highlights the main issues this project aims to resolve, evaluates the approaches to building more idiomatic APIs, and provides library usage examples.
Аннотация: На сегодняшний день доминирующими языками в сфере программирования графики являются C++ и, в значительно меньшей мере, C. Следствием этого является направленность современных графических программных интерфейсов на использование совместно именно с этими языками. Это создаёт затруднения для проектов в данной области, использующих другие языки программирования. В статье рассматривается разработка библиотеки привязок к графическому программному интерфейсу
Direct3D 12 для языка Rust, описываются решаемые данным проектом проблемы, подходы к построению более идиоматичных интерфейсов, а также приводятся примеры его работы.
Key words: Direct3D 12, Rust, graphics APIs
Ключевые слова: Direct3D 12, Rust, графические программные интерфейсы
Введение. Несмотря на то, что для Rust уже существовали проекты привязок для графического API Direct3D 12, например [1][2], все рассмотренные пакеты были недостаточно полными с точки зрения покрытия API, заброшенными или предоставляли недостаточно идиоматичные программные интерфейсы. Учитывая это, а также для полного контроля над кодом одной из важнейших зависимостей, то есть возможности реализовывать в первую очередь необходимую именно на данный момент функциональность, а также поддерживать последние обновления API, например DXR или D3D12 Agility SDK, была разработана собственная библиотека привязок.
Основным инструментом для построения библиотеки является проект с открытым
производным кодом [3], разработанный сотрудниками Mozilla Corporation в соавторстве с сообществом, позволяющим автоматически генерировать обертки файлов заголовков C и определенных форм C++. Поскольку поддержка последнего языка является неполной и несколько усложнена, было решено пользоваться вариантом API D3D12, предназначенным для использования с C, таким образом, во время сборки библиотеки автоматически генерируются привязки, а сам код библиотеки является идиоматическими обертками над сгенерированным кодом, который достаточно трудно использовать напрямую.
Организация файлов библиотеки. Структуру основных каталогов и файлов библиотеки можно описать с помощью следующей диаграммы:
rusty-d3dl2 assets examples
—dynamic indexing,rs —dynamic indexing sm65.rs —hello mesh shaders.rs —hello texture.rs —hello triangle.rs
— heterogeneous multiadapter. rs —interprocess communication.rs
— n body gravity, rs extern
-gD3D12Agility5DK
-1 IwinPixEventRLintime
generation
— d3dl2 wrapper.h
— pix wrapper.cpp
— pix wrapper.h
src
[_|raw bindings
— d3dl2. rs
— mod.rs —pix.rs
-const wrappers. rs -enum wrappers. rs -lib.rs
-struct wrappers, rs -utils.rs
tools
-conversion assist.py
-Cargo.toml -build.rs
Рис. 1. Структура файлов и каталогов библиотеки
Каталог assets содержит объекты, библиотеки, в том числе модель Стэнфордского необходимые для рендеринга примеров работы дракона [4] и шейдеры, а в каталоге examples -
68 East European Scientific Journal #10(74), 2021 исходные коды этих примеров. В каталоге extern сохраняются внешние зависимости проекта, которые не распространяются с помощью менеджера пакетов Cargo, а именно Microsoft Agility и библиотеку для поддержки графического отладчика Pix on Windows.
Главным каталогом библиотеки является src, в котором находится большая часть ее кода:
• в подкаталоге raw bindings находятся пре-генерируемые привязки, что позволяет не запускать rust-bindgen каждый раз при сборке библиотеки, если в этом нет надобности, и таким образом увеличить скорость ее компиляции; обновление этих файлов имеет смысл при обновлении версии Agility SDK, распространяемой с библиотекой, из-за появления новых API,
• файл lib.rs является входной точкой библиотеки и содержит обертки над необходимыми COM-интерфейсами D3D12,
• файл struct wrappers.rs содержит обертки над POD-типами D3D12, которые предоставляют более идиоматический с точки зрения системы типов доступ к их полям,
• файл enum_wrappers.rs содержит обертки над нумерациями и битовыми масками, используемыми в D3D12,
• в файле const_wrappers.rs находятся реэкспортированные из файла «сырых» привязок и переименованные константы,
• и, наконец, файл utils.rs содержит необходимые для работы библиотеки утилиты, такие как тип Bytes и функции для компиляции шейдеров.
Далее описаны основные составляющие разработанной библиотеки, а также ее особенности и возможности.
Сборочный скрипт. Одной из важнейших функций, которые предоставляет менеджер пакетов Cargo, является поддержка сборочных скриптов -вспомогательных программ на Rust, которые выполняются во время сборки пакета и позволяют выполнять произвольное конфигурирование сборочного окружения, копировать необходимые файлы, компилировать написанные на C/C++ зависимости проекта и т.п. Разработанная библиотека использует эту функцию Cargo для реализации двух различных режимов сборки, переключение между которыми осуществляется с помощью свойств проекта (Cargo features). По умолчанию при сборке библиотеки используются распространяемые вместе с ней
прегенерированные исходные файлы с автоматически созданными привязками к заголовочным файлам D3D12, DXGI и PIX, что позволяет уменьшить время сборки и избавиться от зависимости от библиотек LLVM, которые необходимы для генерации привязок. При необходимости же обновления упомянутых заголовочных файлов с помощью свойства devel может быть активирован альтернативный режим сборки, при котором исполняется функция generate_bindings() сборочного скрипта. Эта
ии
вшам
функция применяет некоторые изменения к заголовочному файлу d3d12.h, которые необходимы для исправления несоответствия между прототипами некоторых функций D3D12 (например, GetCP UDescriptorHandleForHeapStart) и их реализаций в библиотеке d3d12.dll, которые могут приводить к аварийному завершению программ, использующих библиотеку. После этого для набора необходимых заголовочных файлов запускается генератор привязок rust-bindgen, который создает обновленные версии файлов d3d12.rs и pix.rs, которые в дальнейшем используются в работе библиотеки. Кроме того, сборочный скрипт выполняет такие функции, как копирование необходимых для работы примеров внешних библиотек в сборочный каталог и передача компилятору rustc дополнительных флагов линковки, которые позволяют экспортировать необходимые для использования D3D12 Agility SDK символы.
Обертки над COM-интерфейсами. Основой графического API D3D12 является компонентная объектная модель Win32 (далее COM, Component Object Model) [5]. В случае работы с данной моделью на языке C++ ее использование не вызывает затруднений благодаря тому, что COM-интерфейсы реализованы как классы C++ и их методы могут быть вызваны напрямую как обычные методы объектов C++, а также наличию вспомогательных библиотек, таких как Windows Runtime C++ Template Library (WRL), которая представляет облегчающие работу с COM типы, например, «умный указатель» ComPtr, который позволяет использовать идиому RAII (Resource Acquisition is Initialization) для автоматического управления количеством ссылок на используемые COM-объекты и, как следствие, их временем жизни. Использование C-интерфейсов же несколько затруднено по сравнению с C++ ввиду отсутствия в языке C классов и наследования, поэтому заголовочные файлы D3D12 предоставляют типы COM в виде структур с соответствующими именами, которые не имеют методов, но имеют единственное поле вспомогательного типа (которые назван аналогично оригинальному интерфейсу с приставкой Vtbl), которое является явным представлением указателя на таблицу виртуальных функций C++. Соответственно, методы каждого из COM-интерфейсов реализованы не на изначальной структуре, а на упомянутом типе, что приводит к необходимости написания излишнего кода для доступа к необходимым методам.
Поскольку привязки для Rust реализованы на основе C-интерфейса, они также подвержены этой проблеме. Для ее решения и повышения удобства использования COM-интерфейсов, а также предоставления возможности отладки проблем, связанных с временем жизни COM-объектов (в частности, их преждевременным разрушением), в библиотеке были реализованы макросы, автоматически извлекающие требуемый метод и
вызывающие его с переданными аргументами прозрачно для пользователя. Реализация одного из этих макросов приведена на скриншоте:
macrorules! dx_call Щ
(îobjectptr: ехрг., iiriethod_name: ident., $(îargs:ехрг),*} let vtbl = jectptr).lpVtbl;
let rawfunc = (*vtbl). $method_naine. ипнгар( ); rawfunciîobjectjtr, îiîargs);,*)
}};
(îfn_naine: ident Îargs:tt) => {Sfn_name îargsj}
Рис. 2. Исходный код макроса для облегчения извлечения методов API из объектов, предоставляемых C-интерфейсом
Необходимость в нескольких макросах обусловлена тем, что некоторые функции D3D12 возвращают код ошибки, а некоторые - нет, поэтому для идиоматичной работы с первым классом функций макрос должен возвращать реализованный в библиотеке тип ошибки DxResult, который позволяет использовать доступную в Rust с помощью оператора ? идиому раннего выхода из функции при ошибке.
Дополнительная функциональность, которую предоставляют разработанные макросы, является аналогичной «умному указателю» ComPtr из библиотеки WRL и позволяет автоматически управлять количеством ссылок на COM-объект с помощью реализации черт (trait) Clone и Drop - при копировании объекта с помощью метода clone() вызывается COM-функция AddRef(),
увеличивающая количество ссылок на единицу, а при разрушении объекта счетчик ссылок уменьшается с помощью вызова комплементарной ей функции Release().
Кроме того, как было упомянуто выше, данные макросы позволяют логировать текущее количество ссылок на COM-объект при включенном свойстве проекта logrefcounting, что облегчает отладку аварийных завершений программы из-за ошибочного освобождения объектов. Данное свойство отключено по умолчанию средствами условной компиляции для избежания засорения логов приложения и ухудшения его производительности.
Обертки над POD-структурами. Другой категорией типов, предоставляемых D3D12, являются plain old data (POD) структуры, например,
D3D12_GRAPHICS_PIPELINE_STATE_DESC. С точки зрения Rust, прямое их использование не является оптимальным, как минимум, с двух точек зрения - во-первых, их поля зачастую не являются типобезопасными и соответственно, могут быть спутаны при разработке приложений, а во-вторых, иногда являются указателями, и при некорректной работе с ними могут приводить к аварийному завершению программы. Обе эти проблемы были решены в разработанной библиотеке. Для
обеспечения типобезопасности доступ к полям обернутых структур осуществляется с помощью get/set методов, которые осуществляют конвертацию между Rust-типами (например, энумерациями) и оригинальными типами, которые зачастую являются синонимами (alias) типа i32. Проблема «висячих указателей» решена с помощью механизма лайфтаймов Rust - обертки над типами, которые содержат в себе указатели, содержат в себе дополнительные поля типа PhantomData, который имеет нулевой размер и не влияет на сгенерированный компилятором код, но может быть параметризован ссылочным типом, связанным с типом, указатель на который содержится во внутреннем типе. Таким образом, компилятор Rust сможет статически гарантировать, что указатель внутри структуры не может иметь более длительный период существования, чем данные, на которые он ссылается. Важным моментом является то, что обертки над данными типами остались бинарно совместимыми с оригинальными типами D3D12 благодаря повсеместному использованию атрибута #[repr(transparent)].
Обертки над энумерациями и битовыми флагами. Помимо COM-интерфейсов и POD-структур, частью интерфейса D3D12 являются энумерации (enums) - например, D3D12_COMMAND_LIST_TYPE, и битовые флаги (например, D3D12_RESOURCE_STATES). В оригинальной версии API они представлены в виде С-энумераций и следовательно, не являются типобезопасными, что может приводить к ошибкам при разработке. Для решения этой проблемы в библиотеке данные типы были обернуты в Rust-энумерации, которые являются не только типобезопасными, но и гарантированно исчерпывающими (exhaustive) и битовые флаги (с помощью библиотеки bitflags), соответственно.
Вспомогательный скрипт для конвертации «сырых» API. Сгенерированный с помощью rust-bindgen файл с типами D3D12 на данный момент содержит около 25 тысяч строк, поэтому без автоматизации процесса создания оберток обеспечение полного покрытия API является
70 East European Scientific Journal #10(74), 2021 затруднительным. С другой стороны, полностью автоматизировать этот процесс также невозможно, поскольку для упрощения работы с API при разработке библиотеки применялись
незначительные, но тем не менее нетривиальные изменения, например, хранение размера указателя на дескриптор внутри самого объекта дескриптора, что позволяет свести получение новых дескрипторов к вызову одного метода advance(), аргументом которого является количество дескрипторов, на которое нужно сместить указатель.
В качестве простого компромисса был разработан вспомогательный скрипт на Python (файл conversion_assist.py), который принимает на вход часть файла с «сырыми» привязками d3d12.rs, а именно - описание энумерации, набора битовых флагов или POD-структуры, разбирает полученный код с помощью регулярных выражений и выводит описание конвертированных типов. Описания перечислений и битовых флагов, которые генерируются скриптов, можно использовать в библиотеке напрямую без изменений, но процесс конвертации структур по причинам, упомянутым выше, является полуавтоматическим, поскольку зачастую сгенерированные описания требуют частичного ручного редактирования (например, замены встроенных типов на созданные ранее обернутые типы или явного указания лайфтаймов).
Agility SDK. До определенного периода компоненты ОС, предоставляющие графическое API Direct3D, распространялись как часть ОС Windows и, соответственно, обновлялись синхронно с ней. Это представляло собой некоторую проблему, а именно - использование новой функциональности разработчиками приложений было затруднено сегментацией пользовательской базы, поскольку у значительной части пользователей отсутствовали необходимые обновления. Для решения этой проблемы компания Microsoft изменила подход к распространению библиотек D3D12: теперь системная библиотека d3d12.dll является тонкой оберткой над предоставляемым API, а основная часть функциональности среды времени выполнения вынесена в отдельную библиотеку d3d12core.dll, которая является частью DirectX12 Agility SDK [6], предлагается к распространению разработчиками приложений и может обновляться согласно потребностям последних.
Поскольку для использования наиболее современных компонентов API использование этого SDK является обязательным, оно было интегрировано в разработанную библиотеку. Для этого, как было упомянуто выше, сборочный скрипт указывает линкеру на файл с определением таблицы экспорта agility.def копирует необходимые для работы примеров библиотеки в сборочный каталог, а сами примеры экспортируют символы D3D12SDKVersion и D3D12SDKPath, что позволяет указать на версию SDK, на которую рассчитано приложение, а также путь к нему. Одна
ЦИ
вшам
из основных возможностей, которые предоставила интеграция Agility SDK в библиотеку, состоит в использовании прямой индексации куч дескрипторов из шейдеров, которая стала доступна с шейдерной моделью версии 6.6.
Средства для отладки. Поскольку современные графические ускорители работают асинхронно относительно центрального процессора, имеют другую модель исполнения программ, а их использование более абстрагировано за счет графических API, отладка использующих их программ представляет собой более сложную задачу, чем отладка «традиционных» программ. Среди инструментов, которые упрощают отладку приложений, которые используют графическое API D3D12 и включены в состав данной библиотеки, стоит отметить уже упомянутые выше макросы для логирования счетчиков ссылок на COM-объекты, а также API для включения автоматического именования объектов API, валидации использования API со стороны графического процессора, использование отладочной функции обратного вызова (debug callback), которая позволяет интегрировать диагностические сообщения среды времени выполнения D3D12 в общую систему логирования приложения, а также поддержку графического отладчика PIX on Windows.
Одна из основных возможностей, которые предоставляются последним - это перехват вызовов графического API, которые совершает приложение, и их последующее воспроизведение внутри самого отладчика, что позволяет захватить конкретный кадр, в котором присутствуют графические артефакты или иные проблемы, и подробно изучить состояние используемых в нем ресурсов, аргументы совершенных вызовов, отладить конкретный вызов шейдера и т.п. Сам по себе этот отладчик может использоваться и без специальной поддеркжи со стороны приложения, но навигация среди сотен или даже тысяч вызовов API внутри одного кадра может составлять серьезную проблему, затрудняющую отладку. Решением этой проблемы является использование специального API, предоставляемого PIX в отдельных от D3D12 заголовочных файлах, которое позволяет помечать регионы выполняемой на графическом процессоре работы пользовательскими маркерами, а также начинать и останавливать запись вызовов в определяемый самим приложением момент (что является необходимым, если, например, приложение отображает результаты своей работы во внеэкранном буфере). Интеграция этого API в библиотеку составила некоторые затруднения, поскольку оно не имеет совместимого с C варианта, а реализовано на C++ таким образом, что генерация автоматических привязок с помощью rust-bindgen является невозможной. Это привело к необходимости ввести дополнительный слой абстракции и обернуть C++ API PIX в набор отдельных функий, помеченных как extern "C" и,
соответственно, пригодных к использованию из Rust. Как было упомянуто выше, генерация Rust-привязок (а также компиляция C-обертки с помощью библиотеки cc) происходит в сборочном скрипте при включенной опции devel, а для поддержки варианта сборки по умолчанию они распространяются вместе с проектом в виде исходного файла со сгенерированными заранее функциями и статической библиотеки со скомпилированным слоем абстракции.
Примеры работы библиотеки. Для обеспечения достаточно полного покрытия D3D12 API, демонстрации соответствия между предоставляемыми библиотекой и оригинальными API, а также верификации корректности ее работы был разработан набор демонстрационных примеров. Наиболее полным из них является программа HeterogeneousMultiadapter (см. рис. 3). Она демонстрирует использование для рендеринга двух графических процессоров одновременно (один из них или оба могут при этом быть как
физическими, так и виртуальными WARP-адаптерами): один из адаптеров объявляется «основным» и применяет эффект размытия к треугольникам, которые генерируются с помощью первого адаптера, а также отображает результат рендеринга на экране. Коммуникация между адаптерами при этом осуществляется с помощью разделенных куч (shared heaps), в которые копируются промежуточные результаты рендеринга. Помимо этого, в данном примере также демонстрируется работа с API для профилирования рендеринга на графическом адаптере: нагрузка на вторичный адаптер может меняться динамически в зависимости от времени выполнения им работы. Данный пример наиболее точно соответствует одному из официальных примеров, предоставляемых Microsoft для ознакомления с D3D12 [7], поэтому является наиболее удобным для первичного ознакомления с библиотекой.
О nit windov - - □ X
▲ A A A * *
A A A * 4 A * A 4 A * »* A » * A A A * * L fe
A A A k A A A \ A A 4 A W * A • • • . A * Д A * • A * *v
A A * A • » Л
aA * К * - * V;; • A*,' / 4
' АЛ a a A 4 ж A A * * **A * О A A • .A • A > ч • A A A A A A A A A
Рис. 3. Скриншот работы примера "Heterogeneous Multiadapter", использующего для рендеринга два графических адаптера одновременно
Заключение. В статье была рассмотрена библиотека привязок к графическому API D3D12, которая позволяет использовать его в программах, написаных на языке Rust. Была описана файловая структура библиотеки, рассмотрены режимы ее работы, а также особенности и предоставляемые возможности. Кроме того, были упомянуты существующие средства отладки программ, использующих графические процессоры с помощью D3D12, сценарии их использования совместно с данной библиотекой, а также приведен пример ее использования, который позволяет сравнить предоставляемые ей интерфейсы с оригинальными.
Список литературы:
1. d3d12-rs / crates.io: Rust Package Registry. URL: https ://crate s. io/crates/d3 d12
2. winapi / crates.io: Rust Package Registry. URL: https://crates.io/crates/winapi
3. rust-bindgen / Github. URL: https://github.com/rust-lang/rust-bindgen
4. Dragon / The Stanford 3D Scanning Repository. URL: http://graphics.stanford.edu/data/3Dscanrep/
5. The Component Object Model / Windows App Development. URL: https://docs.microsoft.com/en-us/windows/win32/com/the-component-object-model
6. Getting Started with the Agility SDK / DirectX Developer Blog. URL: https://devblogs.microsoft.com/directx/gettingstarted-dx12agility/
7. DirectX-Graphics-Samples / Github. URL: https://github.com/microsoft/directx-graphics-samples
