Все подпрограммы исходных библиотек можно разделить на подпрограммы ядра + множество мелких расширений.

Все подпрограммы ядра находятся в классе gl/cl для OpenGL/OpenCL соответственно.

То есть если вы хотите вызвать функцию clCreateBuffer надо писать:

cl.CreateBuffer(...);

По нажатию точки после cl вам так же покажет список всех функций в ядре OpenCL.

С OpenGL немного сложнее:

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

В модуле OpenGL это реализовано так:

//ToDo Создание контекста и привязка его к текущему потоку

// Все адреса и экземпляры делегатов создаются в конструкторе
// В "<>" указывается имя платформы
// Можете написать "Pl" и нажать Ctrl+пробел, чтоб получить список платформ
var gl := new OpenGL.gl<PlWin>;

while true do
begin
  // Локальные переменные имеют бОльший приоритет чем классы
  // Поэтому тут "gl" это не класс, а экземпляр, который создали выше
  gl.Clear( ClearBufferMask.COLOR_BUFFER_BIT );
  
  //ToDo само рисование
  
end;

У каждого расширения есть свой класс. К примеру, так используется расширение GL_AMD_debug_output:

//ToDo Опять же, сначала контекст

var glDebugOutputAMD := new OpenGL.glDebugOutputAMD<PlWin>;
...
glDebugOutputAMD.DebugMessageEnableAMD(...);

В модуле OpenGL так же есть особые классы, wgl, gdi и glx:

gdi содержит несколько методов библиотеки gdi32.dll. На этой библиотеке основано всё в System.Windows.Forms.
Подпрограммы включённые в класс gdi - это то, что может понадобиться вам, чтоб настроить и подготовить форму для рисования на ней с помощью OpenGL.
wgl содержит методы для подключения OpenGL к окну Windows.
glx содержит методы для подключения OpenGL к окну XWindow.

Оба этих класса работают как класс cl, то есть им не надо создавать экземпляр.

И последнее что вам надо знать об этих классах:
Если вы получаете NullReferenceException, при попытке вызова функции из инициализируемых классов, как gl:

Скорее всего вы попытались вызвать подпрограмму, которой нет в реализации библиотеки на вашем компьютере.
Проверьте версию библиотеки, или, если это подпрограмма из расширения - проверьте существование у вас этого расширения.
Так же, возможно, проблема в н.у. модуле. Если вы уверены что п.1. вас не касается - напишите в issue.

Библиотека OpenGL.dll имеет несколько функций, принимающих вектора и матрицы (в основном для передачи значений в шейдеры).

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

Но реализовывать их все в качестве extensionmethod'ов было бы сложно, не красиво, а в случае статичных методов и свойств - ещё и невозможно.

ToDo сейчас все индексные свойства кроме .ColPtr (.val, .Row и .Col) убраны из релиза, потому что я не знаю как безопастно и эффективно их реализовывать. Постараюсь в ближайшее время придумать, что можно сделать.

Векторы

Все типы векторов можно описать разом как Vec[1,2,3,4][ b,ub, s,us, i,ui, i64,ui64, f,d ].

Свойства

У векторов есть только индексное свойство val. Оно принимает индекс, считаемый от 0, и возвращает или задаёт значение вектора для соответствующего измерения.

К примеру:

var v: Vec4d;
v[0] := 123.456; // Записываем 123.456 по индексу 0
v[1].Println; // Читаем и выводим значение по индексу 1
v.val[2] := 1; // Можно так же писать и имя свойства

Но использование этого свойства не рекомендуется. Прямое обращение к полю всегда будет быстрее. То есть аналогично предыдущему коду:

var v: Vec4d;
v.val0 := 123.456;
v.val1.Println;
v.val2 := 1;

Используйте свойство val только тогда, когда индекс это НЕ константа.

Унарные операторы

var v0: Vec3d;
...
// v1 будет иметь ту же длину, но
// противоположное v0 направление
var v1 := -v0;
// А унарный + не делает ничего, он только
// для красоты. То есть v2 будет =v0
var v2 := +v0;

Умножение/деление на скаляр

var v1: Vec3d;
var v2: Vec3i;
...
// Выведет вектор, имеющий то же
// направление что v1, но в 2 раза длиннее
(v1*2).Println;

// Выведет вектор, имеющий то же
// направление что v1, но в 2 раза короче
(v1/2).Println;

// К целочисленным векторам вместо
// обычного деления надо применять div
(v2 div 2).Println;

Операции с 2 векторами

var v1, v2: Vec3d;
...
// Скалярное произведение векторов
(v1*v2).Println;

// Сумма векторов, складывает
// отдельно каждый элемент вектора
(v1+v2).Println;

// Разность векторов, тоже работает
// отдельно на каждый элемент вектора
(v1-v2).Println;

Чтоб применить 1 из этих операций к 2 векторам - их типы должны быть одинаковые.
Если это не так - 1 из них (или оба) надо явно преобразовать, так чтоб типы были одинаковые:

var v1: Vec3d;
var v2: Vec2i;
...
( v1 + Vec3d(v2) ).Println;

SqrLength

Метод .SqrLength возвращает квадрат длины (то есть модуля) вектора.
Возвращаемый тип .SqrLength совпадает с типом элементов вектора.
Каким образом находить корень полученного значения - дело программиста.

var v1: Vec3d;
...
v1.SqrLength.Println; // Квадрат длины
v1.SqrLength.Sqrt.Println; // Сама длина

Normalized

Метод .Normalized возвращает нормализированную (с длиной =1) версию вектора.
Так как эта операция требует деления (на длину вектора), она применима только к векторам с элементами типов single или real (f или d).

var v1 := new Vec3d(1,1,1);
v1.Println;
v1.SqrLength.Sqrt.Println;
var v2 := v1.Normalized;
v2.Println;
v2.SqrLength.Sqrt.Println; // Обязательно будет 1

Cross

Статичные методы .Cross[CW,CCW] возвращают векторное произведение двух 3-х мерных векторов ("Cross product", не путать со скалярным произведением).
Векторное произведение - это вектор, перпендикулярный обоим входным векторам и имеющий длину, равную площади параллелограмма, образованного входными векторами.

Не работает для векторов с элементами-беззнаковыми_целыми, потому что даёт переполнение на практически любых входных значениях. Если найдёте нормальное применение - напишите в issue.

В математике произведение векторов может вернуть один из двух противоположных друг-другу векторов, в зависимости от ориентации системы координат. В модуле OpenGL это решено следующим образом:

Vec3d.CrossCW(new Vec3d(1,0,0), new Vec3d(0,1,0)) = new Vec3d(0,0,1).
Vec3d.CrossCCW(a,b) = -Vec3d.CrossCW(a,b);

Ввод с клавиатуры

Статичные методы Read и Readln создают новый вектор из элементов, прочитанных из стандартного ввода:

// Прочитать 2 числа из ввода
Vec2d.Read('Введите 2 координаты:').Println;

// Прочитать 2 числа из ввода
// и затем пропустить всё до конца строки
Vec2d.Readln.Println;

Превращение в строку

var v1: Vec4d;
...
v1.Println; // Вывод вектора
// s присвоит ту же строку, что выводит .Println
var s := v1.ToString;

Методы .ToString и .Println должны быть использованы только для чего то вроде дебага или красивого вывода, потому что операции со строками это в целом медленно.

Матрицы

Все типы матриц можно описать разом как Mtr[2,3,4]x[2,3,4][f,d].

У каждой квадратной матрицы есть короткий синоним.
К примеру вместо Mtr3x3d можно писать Mtr3d.

Так же стоит заметить - конструктор матрицы принимает элементы по строкам, но в самой матрице элементы хранятся в транспонированном виде.

Это потому, что в OpenGL.dll в шейдерах матрицы хранятся по столбцам.
Но если создавать матрицу конструктором - элементы удобнее передавать по строкам, вот так:

var m := new Mtr3d(
  1,2,3, // (1;2;3) станет нулевой строкой матрицы
  4,5,6,
  7,8,9
);

Свойства

Как и у векторов, у матриц есть свойство val:

var m: Mtr4d;
m[0,0] := 123.456;
m[1,2].Println;
m.val[3,1] := 1;

И как и у векторов - val всегда медленнее прямого обращения к полям:

var m: Mtr4d;
m.val00 := 123.456;
m.val12.Println;
m.val31 := 1;

Но у матриц так же есть свойства для столбцов и строк:

var m: Mtr3d;
...
m.Row0.Println; // Вывод нулевой строчки в виде вектора
m.Row1 := new Vec3d(1,2,3);
m.Col2.Println;

И в качестве аналога val - строку и стобец тоже можно получать по динамическому индексу (но, опять же, это медленнее):

var m: Mtr3d;
...
m.Row[0].Println;
m.Row[1] := new Vec3d(1,2,3);
m.Col[2].Println;

Для столбцов так же есть особые свойства, возвращающие не столбец, а его адрес в памяти:

var m: Mtr3d;
...
var ptr1 := m.ColPtr0;
var ptr2 := m.ColPtr[3];

Использовать это свойство не всегда безопастно.

Оно должно быть использовано только для записей, хранящихся на стеке или в неуправляемой памяти.

Для более безопастной альтернативы - можно использовать методы .UseColPtr*.

Identity

Это тоже свойство, но статичное и применение совершенно другое:

Identity создаёт новую единичную матрицу. То есть матрицу, у которой главная диагональ заполнена 1, а всё останое заполнено 0.

Mtr3d.Identity.Println;
// Работает и для не_квадратных матриц
Mtr2x3d.Identity.Println;

UseColPtr*

Методы .UseColPtr* принимают подпрограмму, принимающую адрес определённого столбца в виде var-параметра.

В отличии от свойств .ColPtr*, методы .UseColPtr* безопастны для матриц, хранящихся в экземплярах классов и статичных полях:

uses OpenGL;

procedure p1(var v: Vec3d);
begin
  Writeln(v);
end;

function f1(var v: Vec3d): string :=
v.ToString;

begin
  var o := new class(
    m := Mtr3d.Identity
  );
  o.m.UseColPtr0(p1);
  o.m.UseColPtr1(f1).Println;
end.

Scale

Статичный метод .Scale возвращает матрицу, при умножении на которую вектор маштабируется в k раз.

var m := Mtr3d.Scale(2);
var v := new Vec3d(1,2,3);
(m*v).Println; // (2;4;6)

Translate

Статичный метод .Translate возвращает матрицу, при умножении на которую к вектору добавляется заданное значение.

var m := Mtr4d.Translate(1,2,3);

// Последний элемент должен быть 1,
// чтобы матрица из .Translate правильно работала
var v := new Vec4d(0,0,0,1);

(m*v).Println; // (1;2;3)

Так же есть статичный метод .TraslateTransposed. Он возвращает ту же матрицу что .Translate, но в транспонированном виде.

2D вращение

Группа статичных методов .Rotate[XY,YZ,ZX][cw,ccw] возвращает матрицу вращения в определённой плоскости.

Первые скобки определяют плоскость.
(Но у 2x2 матриц есть только XY вариант)

Вторые скобки определяют направление вращения:

cw (clock wise): по часовой стрелке
ccw (counter clock wise): против часовой стрелки

3D вращение

Группа статичных методов .Rotate3D[cw,ccw] возвращает матрицу вращения вокруг нормализованного 3-х мерного вектора.
(разумеется, не существует для матриц 2x2,2x3 и 3x2)

Det

Метод .Det возвращает определитель матрицы. Существует только для квадратных матриц.

Transpose

Метод .Transpose возвращает транспонированную версию матрицы:

var m := new Mtr2x3d(
  1,2,3,
  4,5,6
);
m.Transpose.Println; // Выводит:
// 1 4
// 2 5
// 3 6

Умножение матрицы и вектора

m*v - это обычное математическое умножение матрицы m и вектора v, возвращающее результат после применения преобразования из m к v.

Но так же как в шейдерах - поддерживается и обратная запись:
v*m это то же самое что m.Transpose*v.

Умножение 2 матриц

m1*m2 - это математическое умножение матриц m1 и m2.

Ввод с клавиатуры

Статичные методы Read[,ln][Rows,Cols] создают новую матрицу из элементов, прочитанных из стандартного ввода:

// Прочитать 3*4=12 элементов из ввода
// и сохранить в новую матрицу по строкам
Mtr3x4d.ReadRows('Введите 12 элементов матрицы:').Println;

// Прочитать 4 элемета из ввода, переходя на
// следущую строку ввода после чтения каждого столбца
Mtr2d.ReadlnCols(
  'Введите столбцы матрицы...',
  col -> $'Столбец #{col}:'
).Println;

Превращение в строку

Как и у векторов - матрицы можно выводить и превращать в строку

var m: Mtr4d;
...
m.Println; // Вывод матрицы
// s присвоит ту же строку, что выводит .Println
var s := m.ToString;

Для того чтоб матрица выведенная 1 из этих методов выглядела красиво надо использовать моноширный шрифт и поддерживать юникод (потому что для матриц используются символы псевдографики).

Обычно это не проблема для .Println, потому что и консоль, и окно вывода в IDE имеют моноширный шрифт и поддерживают юникод.

Но если выводить на форму, то придётся специально поставить моноширный шрифт.
А если выводить в файл, надо выбрать кодировку файла - юникод (UTF).

В .Net массивы хранят не только содержимое, но и данные о своём размере.

А в C++ вместо обычных массивов используется безформенная область памяти.
При её выделении - в переменную записывается указатель [0] элемента. А о том чтоб сохранить данные о размере этой области - должен позаботится программист.
(вообще обычно в C++ используют обёртки, хранящие длину так же как .Net массивы. Но OpenGL.dll и OpenCL.dll это не касается)

Если вы видели старые коды с использованием OpenGL из какого то из паскалей - наверняка видели что то такое:

glИмяПодпрограммы(@a[0]);

Но в PascalABC.Net так делать нельзя! Получение адреса элемента массива моментально создаёт утечку памяти, потому что компилятор, на всякий случай, вставляет полную блокировку массива в памяти, используя GCHandle с GCHandleType.Pinned.

Такая блокировка нужна, потому что иначе полученный указатель может в любой момент стать устаревшим.

Обычно GCHandle освобождают методом .Free. Но если позволить компилятору использовать GCHandle - освобождение никогда не произойдёт, потому что компилятор не знает когда указатель станет не нужен.

Из очевидных вариантов - использовать GCHandle самостоятельно. Он создаётся статичным методом GCHandle.Alloc. Далее, адрес можно получить методом GCHandle.AddrOfPinnedObject.

Но GCHandle довольно ограничен. К примеру, он может заблокировать array of char, но не array of r, для r - запись, содержащая поле типа char. И то же самое с DateTime и ещё несколькими стандартными типами, которые GCHandle считает "опасными".

Как видно в тесте на странице выше - массив можно заблокировать в памяти без GCHandle, если передавать его параметром-массивом или var-параметром.

И, в отличии от GCHandle, это будет работать с массивами с любым размерным типом элементов.

К примеру, если имеем процедуру p1 из неуправляемой .dll, принимающую массив из двух чисел типа integer:

var a := new integer[5](...);
p1(a); // передача массива целиком
p1(a[3]); // передача [3] элемента var-параметром

Из первого вызова p1 возьмёт только элементы a[0] и a[1], потому что p1 по условию требует только два элемента.

Из второго вызова p1 возьмёт a[3] и a[4], потому что в C++ нет разницы между указателем на один элемент и указателем на начало массива.

Обычнно эти два способа передать массив в неуправляемый код - всё что вам понадобится.

Но, допустим, вы хотите написать подпрограмму для создания OpenGL буфера из массива векторов. Можно сделать перегрузку для каждого типа вектора, но тогда получится очень много дублей кода. Этого довольно просто избежать, используя шаблоны:

// это не настоящая подпрограмма, а только пример
procedure FillBuffer(var data: byte);
external 'some.dll';

// external подпрограммы не могут быть шаблонными, поэтому нужна ещё одна промежуточная перегрузка
// "where T: record;" делает так, что FillBuffer будет можно вызвать только для размерных типов T
procedure FillBuffer<T>(var data: T); where T: record;
begin
  // Компилятор развернёт это в "FillBuffer(data)"
  // То есть никакие преобразования в .exe не попадут
  // Но указатели всё равно нужны, чтоб компилятор не ругался на несовместимость типов
  FillBuffer(PByte(pointer(@data))^);
end;

procedure FillBuffer<T>(data: array of T); where T: record;
begin
  // В C++ нет разницы между массивом и адресом начала его содержимого
  // Поэтому можно передавать массив в виде [0] элемента-var-параметра.
  FillBuffer(data[0]);
end;

Но это для одномерных массивов. А что насчёт многомерных?

Сделать перегрузку для заданного кол-ва измерений не сложно:

procedure FillBuffer<T>(data: array[,] of T); where T: record;
begin
  // Многомерные массивы расположены в памяти как одномерные,
  // Но обращение к элементам идёт по нескольким индексам
  // Элемент [0,0,...] в любом случае будет в самом начале,
  // Поэтому кол-во измерений не влияет на сложность кода
  // Элемент [x,y] будет расположен на позиции "x*h+y", где "h" - кол-во допустимых значений "y"
  FillBuffer(data[0,0]);
end;

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

И, к сожалению, в данном случае я не знаю красивого способа обхода.
Лучшее что я могу придумать - создать Dictionary<integer, Action<System.Array>>, где ключи - размерности массивов, а значения - делегаты, работающие с соответствующей размерностью.
Когда происходит вызов с массивом определённой размерности - создавать новый делегат в виде динамичного метода, с помощью System.Reflection.Emit, если его ещё нет в словаре.

Делегат - это адрес подпрограммы:

procedure p1(i: integer);
begin
  Writeln(i);
end;

begin
  
  var d: System.Delegate := p1; // это не вызов, а получение адреса p1
  d.DynamicInvoke(5); // вообще .DynamicInvoke это очень медленно
  
  var p: integer->();
  // Такое же объявление как на предыдущей строчке, но в другом стиле
//  var p: Action<integer>;
  // И ещё один стиль. Этот особенный, потому что
  // он неявно создаёт новый тип делегата
//  var p: procedure(i: integer);
  p := p1;
  
  // Типизированные делегаты можно вызывать быстрее и проще,
  // так же как обычные подпрограммы
  p(5);
  
end.

Так же как обычные подпрограммы - подпрограммы из неуправляемых .dll могут принимать делегаты параметром.
Далее всё будет рассматриваться на примере cl.SetEventCallback из модуля OpenCL, потому что с ним есть особые проблемы.

Объявление cl.SetEventCallback:

    static function SetEventCallback(&event: cl_event; command_exec_callback_type: CommandExecutionStatus; pfn_notify: EventCallback; user_data: IntPtr): ErrorCode;

Объявление EventCallback:

  EventCallback = procedure(&event: cl_event; event_command_status: CommandExecutionStatus; user_data: IntPtr);

Рассмотрим следующий пример:

uses System;
uses OpenCL;

begin
  
  var cb: EventCallback := (ev,st,data)->
  begin
    Writeln($'{ev} перешёл в состояние {st}');
  end;
  
  var ev: cl_event; //ToDo := ...
  
  cl.SetEventCallback(ev, CommandExecutionStatus.COMPLETE, cb,IntPtr.Zero).RaiseIfError;
end.

Этот код может время от времени вылетать, потому что:

cl.SetEventCallback вызывает свой коллбек тогда, когда посчитает нужным (но обычно после того как вызов cl.SetEventCallback завершился);
Делегаты - это классы.
Сборщик мусора распоряжается памятью классов и удаляет их, тоже когда посчитает нужным.

Раз после вызова cl.SetEventCallback делегат cb больше нигде не используется - сборщик мусора может в любой момент решить удалить его. Но, опять же, это редко случается сразу после вызова cl.SetEventCallback, поэтому ошибки связанные с этим удалением могут быть плавающие.

Если сборщик мусора удалит делегат, а затем .dll попытается его вызвать - это приведёт или к ошибке доступа, или к моментальному беззвучному вылету.

Чтоб запретить сборщику мусора удалять делегать - нужно создать GCHandle, привязанный к нему.
Но в отличии от массивов - GCHandleType.Pinned не нужно, потому что сборщик мусора не может перемещать адрес исполняемого кода (а он единственное что передаётся в .dll). Это потому, что этот адрес хранится в виде указателя на неуправляемый код.

uses System.Runtime.InteropServices;
uses System;
uses OpenCL;

begin
  
  var gc_hnd: GCHandle;
  var cb: EventCallback := (ev,st,data)->
  begin
    
    Writeln($'{ev} перешёл в состояние {st}');
    
    // В данном случае освобождать GCHandle станет можно тогда, когда делегат 1 раз выполнится,
    // А значит очень удобно поставить освобождение в конец самого делегата
    gc_hnd.Free;
  end;
  gc_hnd := GCHandle.Alloc(cb);
  
  var ev: cl_event; //ToDo := ...
  
  cl.SetEventCallback(ev, CommandExecutionStatus.COMPLETE, cb,IntPtr.Zero).RaiseIfError;
end.

Отношение к высоко-уровневым модулям

Багтрагер

Fixers

MiscInput

Log

В кратце:

Подробнее о структуре модулей:

Исключения из общих принципов:

Векторы

Свойства

Унарные операторы

Умножение/деление на скаляр

Операции с 2 векторами

SqrLength

Normalized

Cross

Ввод с клавиатуры

Превращение в строку

Матрицы

Свойства

Identity

UseColPtr*

Scale

Translate

2D вращение

3D вращение

Det

Transpose

Умножение матрицы и вектора

Умножение 2 матриц

Ввод с клавиатуры

Превращение в строку

Страницы:

В кратце: