1、简介
GenApi 模块解决如何去配置相机的问题。主要的思路是，让相机生产厂商为他们的相机提供机器可以识别的产品说明。这些相机描述文件（camera description files）包含所有需要的信息，用以自动地把相机的属性（features）和其寄存器（registers）相对应。
相机的 Gain 属性是一个典型的例子，假设用户想令 Gain=42 ，利用 GenICam ，通用的软件可以读相机的描述文件并发现，要把 Gain 属性设成 42 意味着向地址为 0x0815 的寄存器写入值 0x2A 。其他要做的工作可能是检查相机是否提供 Gain 属性，并检查要写入的值是否在 Gain 的允许范围内。
请注意，给相机添加新的属性仅仅意味着扩展相机的描述文件，就可以对所有符合 GenICam 标准的程序立即生效。
图 2 显示了配置照相机所涉及的图层。
请注意，本文档中的 GenApi 部分只处理照相机描述文件。它旨在帮助 GenICam 用户理解 GenApi 模块背后的关键思想，并使人们能够编写他们自己的相机描述文件。GenApi 参考实现附带了一个参考手册，展示了最终用户如何使用 GenApi 模块，即使不深入了解本节中介绍的概念。
2、照相机描述文件的基本结构
该摄像机是通过在一个包含一组节点的 XML 文件上进行描述的，每个节点都有一个类型和一个唯一的名称。节点可以相互链接，每个连接都起着一定的作用。图 3 显示了一个非常简单的图形符号示例。节点显示为标记为 “type::name” 的气泡标签，链接显示为标记为角色名称的箭头。
有两个特殊的节点：
- 根节点，可以遍历节点图
- 设备节点，提供到传输层连接。
图 3 由一个简单的配置文件构造而成的图的拓扑结构
图 3 中的增益节点（Gain）为 IntReg 类型，它允许从寄存器中提取一个整数。从根节点上看，这是照相机的一个特性。因此，根节点包含一个名为 pFeature 的链接，它引用了增益节点（Gain）。要读取和写入增益寄存器，增益节点需要访问照相机端口，因此它包含一个到设备节点的链接。该链接被命名为 pPort ，并引用了设备节点。
增益节点（Gain）包含在大端模式下提取两个字节无符号整数所需的所有信息。完整的相机描述文件如下：
<?xml version="1.0" encoding="utf-8"?> <RegisterDescription ModelName="Example01" VendorName="Test" ToolTip="Example 01 from the GenApi standard" StandardNameSpace="None" SchemaMajorVersion="1" SchemaMinorVersion="1" SchemaSubMinorVersion="0" MajorVersion="1" MinorVersion="0" SubMinorVersion="0" ProductGuid="1F3C6A72-7842-4edd-9130-E2E90A2058BA" VersionGuid="7645D2A1-A41E-4ac6-B486-1531FB7BECE6" xmlns="http://www.genicam.org/GenApi/Version_1_1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.genicam.org/GenApi/Version_1_1 http://www.genicam.org/GenApi/GenApiSchema_Version_1_1.xsd"> <Category Name="Root"> <ToolTip>Entry for traversing the node graph</ToolTip> <pFeature>Gain</pFeature> </Category> <IntReg Name="Gain"> <ToolTip>Access node for the camera's Gain feature</ToolTip> <Address>0x0815</Address> <Length>2</Length> <AccessMode>RW</AccessMode> <pPort>Device</pPort> <Sign>Unsigned</Sign> <Endianess>BigEndian</Endianess> </IntReg> <Port Name="Device"> <ToolTip> Port node giving access to the camera</ToolTip> </Port> </RegisterDescription>
<?xml> 节点是一个处理元素，提供有关文件编码的提示，并且总是这样的。
<RegisterDescription> 元素是封装摄像机所有节点的最外层括号。相机由模型名称（ModelName）和 VenderName 属性标识标识。
每个节点都有一个可选的 <ToolTip> 元素，其中包含一个简短的描述。增益节点（Gain）有一些依赖于其 IntReg 类型的附加元素，并告诉我们，例如，寄存器的地址或它的长度。其默认值为空字符串。
通常，一个实现将为每个节点创建一个软件对象，并根据 XML 文件中描述的逻辑链接将这些对象链接在一起。这些节点既可以通过它们的（唯一的）名称来检索，也可以通过从根节点开始遍历节点图来找到。一旦用户有了一个指向节点的指针，他就可以通过节点对象的编程接口访问该特性。
XML 文件的语法是在由模式位置属性给出的 XML 模式中定义的。该模式是该标准的一部分。本文解释了 GenICam 的思想和总体结构。模式及其嵌入的参考文档描述了正式的细节。如果有疑问，模式的内容将覆盖此文本的内容。
文件位置 http://www.genicam.org/GenApi/GenApiSchema_Version_1_1.xsd 对于相机配置文件是必需的，但可以在运行时被重写。
3、节点、接口和抽象特征
Nodes, Interfaces, and Abstract Features
相机描述文件中的每个节点只描述一个项目。基于项目的自然性，节点有一个特定的类型（node type）和一个特定的接口（interface）。目前可用的接口（interfaces）如下（每个接口有一个控件用于映射到 GUI）：
IInteger —— 映射到一个带有 value、min、max 和 increment 的滑动条（slider）
IFloat —— 映射到一个带有 value、min、max 和一个物理单位的滑动条（slider）
IString —— 映射到一个显示字符串的编辑框
IEnumeration —— 映射到一个下拉框
ICommand —— 映射到一个命令按钮
IBoolean —— 映射到一个复选框（check box）
IRegister —— 映射到一个显示 16 进制字符串的编辑框
ICategory —— 映射到一个可以反映相机属性结构的树控件
IPort —— 映射到一个相机端口，通常不用图形显示
第 2.9 节给出了接口特性的更多细节。可用的节点类型在第 2.8 节中说明。可能有多种节点类型实现同样的接口类型。例如，IInteger 接口，被下列（不是全部）节点类型实现：
IntReg —— 根据字节边界，从寄存器取出一个整数
MaskedIntReg —— 从寄存器的一段取出一个整数，例如，从第 8 位到第 12 位
Integer —— 从不同的节点得到 value、min、max 和 increment 属性，合并在一起
每个节点类型从不同的源，用不同的方法取出一个整数值。对于需要输入一个整数值的连接，所有这些节点的输出值都可以用作类型安全的输入。
抽象特征（Abstract features）总是用接口类型（interface type）、名称（name）和含义（meaning）来描述。例如，相机的 Gain（名称）可以被定义为 IInteger（接口类型），并且可以描述相机内的增益（含义）。注意，其它的定义也可能存在，例如，Gain 可以被定义为一个 IEnumeration 或一个 IFloat 。
4、获取和设置值
Getting and Setting Values
当用户读或写一个节点的值，节点会触发节点图内一系列的读写操作。为了说明这一点，图 4 显示了 Gain 属性的一个更复杂的例子。Gain 属性可以抽象成一个 IInteger 接口，通过这个接口，用户可以设置 Value 并且可以读（或其它操作）Min 和 Max 值。图 4 的例子假定相机有 3 个寄存器，一个是 Gain 的 Value ，另两个是 Min 和 Max 。利用 IntReg 节点可以从每个寄存器取出相应的值。名字为 Gain 的 Integer 节点收集并合并这些数据，再通过 IInteger 接口把结果传递出来。
图 4：获取和设置功能时的控制流示例
... <Category Name="Root"> <ToolTip>Entry for traversing the node graph</ToolTip> <pFeature>Gain</pFeature> </Category> <IntReg Name="Gain"> <ToolTip>Access node for the camera's Gain feature</ToolTip> <Address>0x0815</Address> <Length>2</Length> <AccessMode>RW</AccessMode> <pPort>Device</pPort> <Sign>Unsigned</Sign> <Endianess>BigEndian</Endianess> <pValue>GainValue</pValue> <pMin>GainMin</pMin> <pMax>GainMax</pMax> </IntReg> <Port Name="Device"> <ToolTip> Port node giving access to the camera</ToolTip> </Port> ...
如果用户读取 Gain 节点的值，调用会被分派到 GainValue 节点，而 GainValue 节点会通过 IPort 接口向 Device 节点查询正确的寄存器。
如果用户试图设置 Gain 节点的值，实现程序可能首先会从 GainMin 和 GainMax 节点读出 Min 和 Max 值以检查范围。如果输入值在允许的范围内，Gain 节点会通过 GainValue 节点和 Device 节点把值写入相机。注意，根据相应 IntReg 节点的 Cacheable 属性，实现程序可能会把 Min 和 Max 值放入缓存。
5、访问模式
Access Mode
每个节点都有一个下表定义的访问模式：
| Readable | Writable | Implemented | Access Mode |
| ＊ | ＊ | 0 | NI – 未实现 |
| 0 | 0 | 1 | NA – 不可用 |
| 0 | 1 | 1 | WO – 只写 |
| 1 | 0 | 1 | RO – 只读 |
| 1 | 1 | 1 | RW – 读写 |
1 = yes, 0 = no, ＊ = don’t care
属性可能已经被相机实现，但暂时不可用。如果可用，则根据定义，属性被实现并且可以读和/或写。
有些节点由某些元素来控制访问权限，例如寄存器节点（参见 2.8.3）。另外，GenICam 还提供 3 种在运行时改变访问权限的机制。
根据另一个节点的值，属性可能暂时被锁定（locked）。属性在锁定的状态下不可写。根据上面的表格，写标志位暂时强制为 0 。
根据另一个节点的值，属性可能暂时不可用（not available）。根据上面的表格，写标志位和读标志位暂时强制为 0 。
根据另一个节点的值，属性可能没有实现（not implemented）。根据上面的表格，实现标志位始终强制为 0 。
“可用” 和 “已实现” 是不同的，因为 GUI 可能想用不同的方法来处理这两种情况。未实现的属性不会显示给用户；而暂时不可用的项目只是灰色的并且值会被替换，例如替换成 “—” ；暂时被锁定的属性是灰色的，但是属性的值仍然会显示。
以硬件 Trigger 为例来说明让一个属性暂时不可用（temporarily not available）的情况，硬件 Trigger 的值可以为 On 或 Off 。如果 Trigger 是 On ，另外一个属性 TriggerPolarity（触发极性） 变得可用，TriggerPolarity 属性指示硬件信号是 ActiveHigh 还是 ActiveLow 。如果 Trigger 是 Off，则 TriggerPolarity 属性是无意义的，应该被置为灰色。
图 5 显示了这个信息在相机描述文件中如何处理，Trigger 和 TriggerPolarity 属性用 Enumeration 类型的节点来实现，这种类型把一组枚举型的入口映射到整数值。例如，Trigger 属性的入口是 On=1 和 Off=0 。利用 IntReg 类型的节点把整数值映射到寄存器。
图 5 控制一个特性是否可访问
TriggerPolarity 节点有个叫 pIsAvailable 的连接，这个连接需要指向一个提供 IInteger 接口的节点。如果这个被指向的节点的值为 0 ，那么 TriggerPolarity 节点暂时不可访问。
在这个例子中，pIsAvailable 可以直接指向 TriggerReg，因为 Trigger=On 被映射为 1，Trigger=Off 被映射为 0 。如果不是这样的话，一个类型为 IntSwissKnife 的节点会很有用，它能根据数学公式计算其他整数节点的值，并得到一个整数的结果。在 XML 文件中，节点看起来像这个样子：
<IntSwissKnife Name="TriggerEnabled"> <ToolTip>Determines if the Trigger feature is switched on</ToolTip> <pVariable Name="TRIGGER">TriggerReg</pVariable> <Formula>TRIGGER==1</Formula> </IntSwissKnife>
<Formula> 入口的数学公式被计算，得到节点的计算结果。在计算之前，变量的符号名称被对应节点的整数值替换。在本例中，只有一个 <pVariable> 入口指向 TriggerReg 节点，符号名称是 TRIGGER 。这个名称在公式 “TRIGGER==1” 中也有。
如果 GUI 升级了，就会去查看 TriggerPolarity 节点是否可用。而 TriggerPolarity 节点会去检查 IntSwissKnife，而 IntSwissKnife 又会根据 TriggerReg 节点的值去计算结果。
兼容 DCAM 的 1394 相机的 BytesPerPacket 属性是 “暂时锁定属性”（ temporarily locked）的一个典型例子。用户可以改变相机的这个参数，仅当 PC 适配器的 DMA 未被设定为采集图像的时候。设定 DMA 的意思是，传输层查询相机的 BytesPerPacket 参数，并把这个参数设置到 DMA 。这个工作完成后，直到传输层释放 DMA 之后才能改变 BytesPerPacket 。在这之前，相机的这个参数必须被锁定。
注意，相机本身没有办法知道 DMA 是否设置。因此，相机描述文件中 “普通的” 节点不能被用来控制 BytesPerPacket 的锁定状态。
图 6 正在锁定一个特征
GenApi 内的解决方案是提供一个浮动的 Boolean 型节点 TLParamsLocked（参见图 6）。BytesPerPacket 通过 pIsLocked 连接到这个节点。传输层（TL）需要通过更新 TLParasLocked 节点的值来反映其 DMA 状态。在设定 DMA 之前，它会通过令 TLParamsLocked 为 true 的方式来锁定相机参数（例如 BytesPerPacket ），在采集图像完成之后，它会把 TLParamsLocked 设置回 false 。改变 TLParamsLocked 节点会更新所有关联节点的锁定状态，例如 BytesPerPacket 节点。
注意，为保证这种方式正常工作，TLParamsLocked 必须是标准的节点名，并且传输层必须有访问相机的 GenApi 接口的权限。另外，相机描述文件的设计者必须注意哪个参数要被传输层锁定。这个信息包含在传输层标准之中，例如 DCAM 规范，这个规范规定，在采集数据的时候每桢的包数和每个包的大小必须固定。
“属性没有被实现”（ not implemented）的一个典型的例子是，同一个家族的某些相机有 Gamma 属性而有些则没有。如果相机有一个查询位（inquiry bit）来标识是否实现了 Gamma 属性，就可以为这个家族的所有相机维护一个相机描述文件。
图 7 显示了 GenICam 如何处理这种情况。Gamma 属性节点有一个叫 pIsImplemented 的连接指向 GammaInq 节点，GammaInq 节点映射相机的查询位。通常把多个查询位合并到一个寄存器里。为了取得这些位，要使用 MaskedIntReg 节点类型。这个类型有点像 IntReg 节点，但是，你可以像查询整数一样取查询想要的一个或一组连续的位。
图 7 检查是否实现了一个功能
