I）介绍：

  本文档提供了DaVinci Color Transform Language (DCTL)的快速参考和展示，包括语法,API和功能。DCTL的语法类似于C语言，同时具有额外的定义。用户可以使用DCTL代码定义函数来创建视频效果，将其保存到文件中，并在Resolve中运行它。这样的效果作为一个“像素着色器”程序——即它定义了一个过程，以每个给定帧的坐标为每次生成一个像素数据。DCTL代码在不同平台和图形子系统中在DaVinci Resolve中得到GPU加速。在Resolve中，DCTL效果可以作为颜色LUT运行，使用DCTL OFX插件或过渡插件。DCTL效果通常保存为纯文本.dctl文件，但如果需要，开发人员可以进一步将加密dctl保存为.dctle文件进行分发。请参见DCTLs下的加密DCTL Encryption。为了简化，本文档使用“DCTL”一词来指代逻辑单元（程序、函数或效果），而使用更通用的“DCTL”或“DCTL代码”一词来指代语言和语法。

II）DCTL类型：

有两种主要类型的DCTL：

1. transform 变换DCTL对单个片段的每个帧应用一个效果。

2. transition 过渡DCTL在时间上混合两个片段的帧来应用一个效果。

变换DCTL执行颜色变换或创建效果（例如增加帧的亮度-请参考包含的Gain.dctl示例）。用户可以通过以下4种方式应用变换DCTL：

• 创建颜色校正节点，打开上下文菜单，通过LUT选项来选择应用相关dctl

• 创建颜色校正节点，添加ResolveFX DCTL插件，并从DCTL列表中选择所需的DCTL文件

• 在LUT浏览器中，预览结果并选择应用LUT到当前节点

• 打开片段缩略图的上下文菜单，通过LUT选择应用

  transition 过渡DCTL创建场景过渡，例如淡出混合两个片段剪辑之间（请参考DissolveTransition.dctl示例）。过渡DCTL只能在OpenFX DCTL Transition Plugin中使用（位于[ Resolve > Edit Page > OpenFX > Transition > ResolveFX Color > DCTL ]）。

  DCTL过渡插件的使用方式与任何其他过渡插件（Resolve的视频过渡、OpenFX过渡等）相同。添加插件后，用户可以从DCTL列表中选择一个DCTL文件，对应的过渡效果将被应用。

加密DCTL：

在Resolve中，用户可以使用到期日期加密.dctl文件，以分发不公开的效果。加密的.dctle可以在任何Resolve系统中正常分发和使用，直到它过期为止

加密DCTL的方法：从LUT浏览器中，选择所需的.dctl文件，打开上下文菜单，选择“加密DCTL”选项。一个助手对话框会出现，供用户设置加密DCTL的名称、过期日期和输出文件夹。加密的DCTL将具有.dctle扩展名

III）DCTL语法：

DCTL的语法类似于C语言，并使用基本C类型语法比如 - int、float、char*、pointer等。在阅读本文档时，了解C编程语言术语会有所帮助。

额外的DCTL类型包括以下内容：

TEXTURE - 纹理引用类型。

float2、float3和float4 - 分别为2个、3个和4个浮点值的向量类型。

实用函数make_float2(float，float)、make_float3(float，float，float)和make_float4(float，float，float，float)可用于构造它们。

这些限定符用于：

DEVICE - 限定符：用于定义函数

CONSTANT - 限定符：用于定义常量内存

CONSTANTREF - 限定符：用于将常量内存参数传递给函数

可以使用“typedef struct”语法来定义结构体，例如：

typedef struct { float c00, c01, c02; float c10, c11, c12; } Matrix;

使用__CONSTANT__来限定常量内存变量。

__CONSTANT__ float NORM[] = {1.0f / 3.0f, 1.0f / 3.0f, 1.0f / 3.0f};

要将常量内存作为函数参数传递，请使用__CONSTANTREF__限定符。

__DEVICE__ float DoSomething(__CONSTANTREF__ float* p_Params)

DCTL编程环境还允许只读访问多个全局常量。这些在下面各节的上下文中进行了描述。

1）主入口函数 The Main Entry Function：

每个DCTL文件必须使用一个名为'transform()'或'transition()'的单个主入口函数，并具有下面所示的函数签名。注意：请完全按照下面的函数定义使用 - 包括参数类型和名称。

变换DCTL的Transform入口函数应为以下之一：

1

 __DEVICE__ float3 transform(int p_Width, int p_Height, int p_X, int p_Y, float p_R, float p_G, float p_B)

2 

__DEVICE__ float3 transform(int p_Width, int p_Height, int p_X, int p_Y, __TEXTURE__ p_TexR, __TEXTURE__ p_TexG, __TEXTURE__ p_TexB)

代码描述：

   该函数在提供的输入参数的基础上，在单个图像（0、0、p_Width、p_Height）的偏移量（p_X，p_Y）处执行像素转换。

参数解释：

* p_Width和p_Height - 图像分辨率即为画面的高和宽

* p_X和p_Y - 转换函数执行颜色转换的像素坐标

* (p_R，p_G，p_B) - 输入像素的RGB值（在第一个签名中）

* (p_TexR，p_TexG，p_TexB) - RGB的纹理引用（在第二个签名中）

函数可以通过调用_tex2D([textureVariable]，[posX]，[posY])请求图像中任何像素的RGB值，返回一个浮点值（posX和posY是所需的输入像素坐标）。

返回值 Returns：

两个变换函数为结果图像中的每个像素坐标（p_X，p_Y）返回一个float3（RGB）值

过渡DCTL的Transition函数使用以下签名：

__DEVICE__ float4 transition(int p_Width, int p_Height, int p_X, int p_Y, __TEXTURE__ p_FromTexR, __TEXTURE__ p_FromTexG, __TEXTURE__ p_FromTexB, __TEXTURE__ p_FromTexA, __TEXTURE__ p_ToTexR, __TEXTURE__ p_ToTexG, __TEXTURE__ p_ToTexB, __TEXTURE__ p_ToTexA)

描述： 该代码可以执行在时间线上从一个片段到另一个片段进行淡入淡出的混合。随着过渡的进行，DCTL逻辑会从“From”和“To”片段中选择适当的图像，并为每个混合请求调用此函数。函数内可以使用全局只读浮点变量“TRANSITION_PROGRESS”来监视过渡的进度，范围从0（即将开始的过渡）到1（过渡已结束）。请参见“其他DCTL关键字”部分。

参数：

* p_Width和p_Height - 输出图像分辨率

* p_X和p_Y - 存储混合结果的输出像素坐标

* (p_FromTexR，p_FromTexG，p_FromTexB) - 过渡变化时图像的RGB纹理引用。 

* (p_ToTexR，p_ToTexG，p_ToTexB) - 过渡变化时图像的RGB纹理引用。

与第二个变换签名类似，函数可以使用_tex2D([textureVariable]，[posX]，[posY])函数访问“From”和“To”纹理中任何像素的RGB值。

返回值returns： 过渡函数为结果图像中的每个像素坐标（p_X，p_Y）返回一个float4（RGBA）值。

2）包含头文件 Including Headers：

您可以将常用的DCTL逻辑添加到一个头文件中，以便在多个效果中调用。要包含头文件，请添加以下条目：

#include "[pathToHeader]"

路径和头文件的位置是相对于DCTL文件的位置的。

一旦包含，就可以在包含点之后引用和使用此头文件中的函数。

4）在DCTL中定义和使用LUT：

色彩查找表（LUT）可以从外部文件中引用，并使用DEFINE_LUT和APPLY_LUT函数应用。  DEFINE_LUT([lutName], [lutPath]);

参数解释： [lutName]是LUT的用户定义名称 - [lutPath]是指向外部LUT文件的路径。可以使用绝对路径和相对于DCTL位置的路径。

 APPLY_LUT(r, g, b, [lutName]);

参数解释：  (r, g, b)是LUT的rgb坐标 - [lutName]是用户定义的LUT名称 - 这必须与先前的DEFINE_LUT或DEFINE_CUBE_LUT调用相匹配（见下文）。

自DaVinci Resolve 17起，可以使用DEFINE_CUBE_LUT函数内联定义LUT。 DEFINE_CUBE_LUT([lutName])  

{ 

[LUT_Content] 

}

参数解释： - [LUT_Content]即是lut代码，应该用花括号'{}'括起来，并且需要遵循CUBE LUT标准格式。 - 可以使用APPLY_LUT函数以与引用的LUT相同的方式应用这些LUT。

以下规则适用：

•  - LUT必须在使用之前在DCTL文件中定义。 

• - 可以在单个DCTL中定义和应用多个LUT。

•  - 可以在DCTL文件中定义多个CUBE LUT，并且可以放置在DCTL的主入口函数之前或之后。 

• - LUT文件必须是.cube格式，1D或3D LUT

• - 1D LUT/Shaper LUT将使用LINEAR线性插值方法应用

• - 3D LUT将根据在达芬奇Resolve中设置的[项目设置>颜色管理>3D查找表插值]中设置的TRILINEAR三线性或TETRAHEDRAL四面体插值方法来应用

4）其他DCTL关键字：

__RESOLVE_VER_MAJOR__和__RESOLVE_VER_MINOR__关键字包含用于检查和保护特定版本DCTL逻辑的版本值。

例如：对于Resolve 17.0，

RESOLVE_VER_MAJOR = 17，RESOLVE_VER_MINOR = 0。 #if ((RESOLVE_VER_MAJOR >= 17) && (RESOLVE_VER_MINOR >= 0)) CallResolve17SpecificLogic(); #else CallAlternativeLogic(); #endif

DEVICE_IS_CUDA，DEVICE_IS_OPENCL，DEVICE_IS_METAL关键字用于用户在CUDA、OpenCL和Metal环境中有条件地检查和执行代码。 

例如：#ifdef DEVICE_IS_CUDA DoSomethingCUDASpecific(); #endif

对于Transition DCTLs，TRANSITION_PROGRESS关键字将当前转换状态的进度作为浮点值保存，范围为[0.0f，1.0f]。在转换期间，DaVinci Resolve更新TRANSITION_PROGRESS值，并为每个图像调用转换主入口函数。DissolveTransition.dctl示例说明如何使用此关键字。