使用视图背景

视图背景概述

视图背景是基本 Visualize 图形视图对象功能的一部分。Visualize API 提供了几个用于处理视图背景的类：

OdTvGsViewBackgroundId — 用于处理视图背景标识符的类。
OdTvGsViewSolidBackground - 用于处理纯色视图背景的类。
OdTvGsViewGradientBackground - 用于处理渐变视图背景的类。
OdTvGsViewImageBackground - 用于处理图像视图背景的类。
OdTvGsViewEnvironmentBackground - 用于处理环境视图背景的类。
OdTvGsViewBackgroundsIterator - 用于处理视图背景迭代器的类。
OdTvGsViewBackgroundsIteratorPtr - 指向纯色视图背景迭代器实例的类型化智能指针。用于存储和传递对纯色视图背景迭代器对象的引用。
OdTvGsViewSolidBackgroundPtr - 指向纯色视图背景实例的类型化智能指针。用于存储和传递对纯色视图背景对象的引用。
OdTvGsViewGradientBackgroundPtr - 指向渐变视图背景实例的类型化智能指针。用于存储和传递对渐变视图背景对象的引用。
OdTvGsViewEnvironmentBackgroundPtr - 指向环境视图背景实例的类型化智能指针。用于存储和传递对环境视图背景对象的引用。
OdTvGsViewImageBackgroundPtr - 指向图像视图背景实例的类型化智能指针。用于存储和传递对图像视图背景对象的引用。

可以创建三种类型的视图背景：

纯色背景
渐变背景
图像背景
环境背景

一个特定的视图一次只能有一个视图背景。

要创建视图背景：

通过使用全局函数 odTvGetFactory 获取工厂 ID：
```
OdTvFactoryId tvFactory = odTvGetFactory();
```
声明一个 OdTvResult 变量，该变量将存储方法执行的结果。如果方法成功执行，它将 OdTvResult 值设置为或返回 tvOk，否则它将包含适当的错误代码。
```
OdTvResult rc;
```
使用工厂对象打开或创建一个新的 Visualize SDK 数据库（在代码片段中创建了一个新的空数据库）。获取指向所创建数据库的智能指针：
```
OdTvDatabaseId databaseId = tvFactory.createDatabase(&rc);
OdTvDatabasePtr dbPtr = databaseId.openObject(OdTv::kForWrite, &rc);
```
在数据库中创建一个新设备。可以创建多种类型的设备。在此示例中，创建了最简单的设备类型 - 非设置设备。获取指向所创建设备的智能指针：
```
OdTvGsDeviceId deviceId0 = dbPtr->createDevice(OD_T("Device0"), &rc);
OdTvGsDevicePtr pDevice0 = deviceId0.openObject(OdTv::kForWrite, &rc);
```
创建一个新的视图对象。视图对象是通过调用设备的 createView() 方法创建的。您需要指定一个视图名称，该名称在数据库中必须是唯一的。另外两个参数是可选的 - 一个布尔值，指定视图是否需要保存到文件中，第二个可选参数接受方法执行的代码。如果方法成功完成，此参数将设置为 tvOk。该方法返回所创建视图对象的标识符。
```
OdTvGsViewId viewId0 = pDevice0->createView(OD_T("View_0"), true, &rc);
```

获取指向所创建视图的智能指针：


OdTvGsViewPtr pView0 = viewId0.openObject(OdTv::kForWrite, &rc);

在数据库中创建一个视图背景并获取指向该视图背景的智能指针。视图背景是使用数据库的 createBackground() 方法创建的。创建视图背景时，您需要指定其名称和类型（来自 OdTvGsViewBackgroundId::BackgroundTypes 枚举的值）。还有一个 OdTvResult 类型的可选参数，用于保存方法执行的结果。在此示例中，创建了一个纯色背景。
```
OdTvGsViewBackgroundId solidBackgroundId0 = dbPtr->createBackground(OD_T("SolidBackground_0"), OdTvGsViewBackgroundId::kSolid, &rc);
OdTvGsViewSolidBackgroundPtr pSolidBackground = solidBackgroundId0.openAsSolidBackground(OdTv::kForWrite, &rc);
```

当您获得视图背景的智能指针时，您可以管理其属性。

在数据库中管理视图背景

Visualize API 提供了与数据库中背景进行基本交互的方法。创建至少一个视图背景后，您可以按名称搜索背景 ID、迭代背景、删除特定背景并清除所有背景。接下来的几个示例展示了如何执行这些操作。


// Searching for background ID by its name
// if background is not found, then searchedBackgroundId.isNull() returns true
OdTvGsViewBackgroundId searchedBackgroundId = dbPtr->findBackground(OdString("SolidBackground_0"));

// Retrieving background IDs with iterator and appending to an array
OdTvGsViewBackgroundsIteratorPtr pIter = dbPtr->getBackgroundsIterator(&rc);
OdArray<OdTvGsViewBackgroundId> backgroundIdsArr;
OdTvGsDeviceId bgId;

while (!pIter->done())
{
  bgId = pIter->getGsViewBackground(&rc)
  if(!bgId.isNull()) // if identifier is not NULL
  {
    backgroundIdsArr.append(bgId);
  }
  pIter->step()
}

// Removing a background by the ID
rc = dbPtr->removeBackground(searchedBackgroundId);

// Clear all backgrounds
rc = dbPtr->clearBackgrounds();

纯色视图背景

纯色背景是一种只显示一种特定颜色的背景。纯色背景根据其颜色和名称最容易管理。

要管理纯色背景的颜色，请分别使用 setColorSolid() 和 getColorSolid() 方法来设置和获取颜色。默认背景颜色为黑色。


// OdTvColorDef OdTvGsViewSolidBackground::getColorSolid(OdTvResult* rc = NULL)
OdTvColorDef solidColor = pSolidBackground->getColorSolid(&rc);

// OdTvResult OdTvGsViewSolidBackground::setColorSolid(const OdTvColorDef& color)
pSolidBackground->setColorSolid(OdTvColorDef(128, 255, 128));

纯色视图背景的名称可以是任意非空字符串，其中可以包含字母、数字、空格、下划线和一些特殊字符，但不能包含不允许的字符（“<”、“>”、“\”、“/”、“:”、“;”、“?”、“,”、“*”、“|”、“=”、“'”、引号以及一些用 Unicode 字体创建的特殊字符）。要设置背景名称，请使用 setName() 方法。使用 getName() 方法检索表示背景名称的字符串。此功能也适用于其他类型的背景。


// OdString OdTvGsViewSolidBackground::getName(OdTvResult* rc = NULL)
OdString solidBgName = pSolidBackground->getName(&rc);

// OdTvResult OdTvGsViewSolidBackground::setName(const OdString& sName)
rc = pSolidBackground->setName(OdString("SolidBG_0"));

渐变视图背景

渐变背景是一种显示三种相互融合颜色的背景。要创建渐变背景，请遵循此处提供的说明，但在最后一步中，将 OdTvGsViewBackgroundId::kGradient 值而不是 OdTvGsViewBackgroundId::kSolid 传递给 createBackground() 方法。

管理渐变背景的颜色

渐变背景由三种颜色组成——底部、中部和顶部颜色。默认情况下，这三种颜色都是黑色。要设置这些颜色，请使用 OdTvGsViewGradientBackground 接口的相应 set 方法，例如 setColorBottom() 方法。您也可以使用相应的 get 方法获取颜色。

下一个示例展示了如何使用这些方法。


// OdTvColorDef OdTvGsViewGradientBackground::getColorBottom(OdTvResult* rc = NULL) const
OdTvColorDef bottomColor = pGradientBackground->getColorBottom(&rc);

// OdTvColorDef OdTvGsViewGradientBackground::getColorMiddle(OdTvResult* rc = NULL) const
OdTvColorDef middleColor = pGradientBackground->getColorMiddle(&rc);

// OdTvColorDef OdTvGsViewGradientBackground::getColorTop(OdTvResult* rc = NULL) const
OdTvColorDef topColor = pGradientBackground->getColorTop(&rc);


// OdTvResult OdTvGsViewGradientBackground::setColorBottom(const OdTvColorDef& color)
rc = pGradientBackground->setColorBottom(OdTvColorDef(255, 0, 0));

// OdTvResult OdTvGsViewGradientBackground::setColorMiddle(const OdTvColorDef& color)
rc = pGradientBackground->setColorMiddle(OdTvColorDef(0, 0, 255));

// OdTvResult OdTvGsViewGradientBackground::setColorTop(const OdTvColorDef& color)
rc = pGradientBackground->setColorTop(OdTvColorDef(0, 255, 0));

管理渐变背景的变换属性

渐变背景由前面描述的三种颜色组成。您可以使用 setHorizon() 和 setHeight() 方法设置颜色覆盖的比例。这里的 horizon 是一个在 [0, 1] 范围内的双精度值，其中 0 对应于设备窗口 x 轴和 y 轴的 0 坐标，1 对应于最大坐标。例如，setHorizon(0.5) 方法调用将中间颜色设置为位于窗口的中间（如果未应用旋转，这是默认设置）。

height 参数控制中间颜色的覆盖范围。例如，setHeight(0.1) 方法调用将中间颜色设置为占据窗口空间（默认在 y 轴上）的 10%。

另外两种颜色由中间颜色分隔，其窗口覆盖范围取决于变换属性。例如，setHorizon(0.5) 和 setHeight(0.001) 方法调用表明另外两种颜色均匀分布并占据几乎所有窗口空间。

您还可以通过调用 setRotation() 方法来旋转背景。此方法接受一个双精度值，该值指定旋转的度数。旋转以逆时针方向测量。请注意，度数的测量方式可能与您预期不同。45 度角表示水平线将从点 (0.0, 0.0) 延伸到点 (1.0, 1.0)，代表设备窗口坐标的起点和终点。

还有用于获取变换背景属性值的 get 方法。

下一个示例演示如何使用与背景变换属性相关的方法。


// double OdTvGsViewGradientBackground::getHorizon(OdTvResult* rc = NULL) const
double dHorizon = pGradientBackground->getHorizon(&rc);

// double OdTvGsViewGradientBackground::getHeight(OdTvResult* rc = NULL) const
double dHeight = pGradientBackground->getHeight(&rc);

// double OdTvGsViewGradientBackground::getRotation(OdTvResult* rc = NULL) const
double dRotation = pGradientBackground->getRotation(&rc);


// OdTvResult OdTvGsViewGradientBackground::setHorizon(double dHorizon)
rc = pGradientBackground->setHorizon(0.33);

// OdTvResult OdTvGsViewGradientBackground::setHeight(double dHeight)
rc = pGradientBackground->setHeight(0.66);

// OdTvResult OdTvGsViewGradientBackground::setRotation(double dRotation)
rc = pGradientBackground->setRotation(45.0);

图像视图背景

图像背景是一种从文件中显示图像的背景类型。当您需要对尝试重新创建的蓝图或绘图进行视觉参考时，图像背景会很有用。要创建图像背景，请遵循此处提供的说明，但在最后一步中，将 OdTvGsViewBackgroundId::kImage 值而不是 OdTvGsViewBackgroundId::kSolid 传递给 createBackground() 方法。

管理图像背景的图像路径

要显示图像背景，请设置加载图像的文件路径。使用 setImageFilename() 方法指定要加载的路径和文件名（带扩展名）。您还可以使用 getImageFilename() 方法获取加载图像的文件路径。


// OdTvResult OdTvGsViewImageBackground::setImageFilename(const OdString& filename)
rc = pImageBackground->setImageFilename(OdString("D://example_files//ODA2.png"));

// OdString OdTvGsViewImageBackground::getImageFilename(OdTvResult* rc = NULL) const
OdString imageFileName = pImageBackground->getImageFilename(&rc);

使图像适应屏幕

背景图像直接映射到其显示的绘图区域。通常，用于创建背景的图像不能完美地适应设备窗口。您可以使用与缩放相关的方法，但是您需要非常精确地使用它们，并且通常很难使用这些方法使图像完美地适应设备窗口。相反，您可以使用 setFitToScreen() 方法自动调整图像大小以适应设备窗口。如果您希望在适应窗口时保持纵横比不变，您还可以使用 setMaintainAspectRatio() 方法。


// bool OdTvGsViewImageBackground::getFitToScreen(OdTvResult* rc = NULL) const
bool bFitToScreen = pImageBackground->getFitToScreen(&rc);

// OdTvResult OdTvGsViewImageBackground::setFitToScreen(bool bFitToScreen)
rc = pImageBackground->setFitToScreen(true);


// bool OdTvGsViewImageBackground::getMaintainAspectRatio(OdTvResult* rc = NULL) const
bool bKeepAspectRatio = pImageBackground->getMaintainAspectRatio(&rc);

// OdTvResult OdTvGsViewImageBackground::setMaintainAspectRatio(bool bMaintainAspectRatio)
rc = pImageBackground->setMaintainAspectRatio(true);

当背景图像占据的空间小于设备窗口时（通常在缩放比例较小或图像本身较小时），您可以选择平铺图像。这样，背景会在所有方向上重复。要调整重复次数，请使用与缩放相关的方法并通过使用与偏移相关的方法调整副本的位置。


// bool OdTvGsViewImageBackground::getUseTiling(OdTvResult* rc = NULL) const
bool bUseTiling = pImageBackground->getUseTiling(&rc);

// OdTvResult OdTvGsViewImageBackground::setUseTiling(bool bUseTiling)
rc = pImageBackground->setUseTiling(true);

管理图像背景偏移

默认情况下，图像背景位于绘图区域的中心，锚点位于图像的中心。图像背景可以单独按 x 轴和 y 轴偏移。getXOffset() 和 getYOffset() 方法返回背景偏移的像素数。如果这两个方法都返回 0.0 值，则背景居中于绘图区域。setXOffset() 和 setYOffset() 方法允许您指定背景从中心偏移的量。


// double OdTvGsViewImageBackground::getXOffset(OdTvResult* rc = NULL) const
double dXOffset = pImageBackground->getXOffset(&rc);

// double OdTvGsViewImageBackground::getYOffset(OdTvResult* rc = NULL) const
double dYOffset = pImageBackground->getYOffset(&rc);

// OdTvResult OdTvGsViewImageBackground::setXOffset(double dXOffset)
rc = pImageBackground->setXOffset(0.0);

// OdTvResult OdTvGsViewImageBackground::setYOffset(double dYOffset)
rc = pImageBackground->setYOffset(200.0);

管理图像背景缩放

背景图像通常不适合绘图区域，反之亦然——它们可能太小，因此您可能需要调整图像背景的比例。要调整图像背景的比例，请分别使用 setXScale() 和 setYScale() 方法来调整 x 轴和 y 轴。要检索 x 轴和 y 轴上的图像背景比例，请使用 getXScale() 和 getYScale() 方法。图像背景比例在两个轴上默认为 1.0。


// double OdTvGsViewImageBackground::getXScale(OdTvResult* rc = NULL) const
double dXScale = pImageBackground->getXScale(&rc);

// double OdTvGsViewImageBackground::getYScale(OdTvResult* rc = NULL) const
double dYScale = pImageBackground->getYScale(&rc);

// OdTvResult OdTvGsViewImageBackground::setXScale(double dXScale)
rc = pImageBackground->setXScale(2.0);

// OdTvResult OdTvGsViewImageBackground::setYScale(double dYScale)
rc = pImageBackground->setYScale(2.0);

环境视图背景

环境背景是一种背景，它在静态背景上具有栅格图像，并在图形场景中具有材质反射。环境可以是立方体（CubeMap）或球形（SphereMap）。

您可以使用以下方式指定立方体贴图：

特定的 .ocm 文件（有关更多详细信息，请参阅可视化立方体贴图）。
栅格图像。栅格图像的高度必须大于宽度，并且边长应可分为相等的图块：两个水平和三个垂直。仅当设置了栅格且不满足这些条件时才使用球体贴图。

以下代码展示了如何创建环境背景、获取此对象的指针并设置参数。OdTvDatabasePtr pDatabase 是 Visualize 数据库实例的指针。


OdTvResult rc;
OdTvGsViewBackgroundId backgroundId = pDatabase->createBackground("EnvironmentBackground0", OdTvGsViewBackgroundId::kEnvironment, &rc);
OdTvGsViewEnvironmentBackgroundPtr pBackground = backgroundId.openAsEnvironmentBackground(OdTv::kForWrite);
rc = pBackground->setEnvironmentImageFileName("D:\\Files\\VIS-2717\\FjaderholmarnaSphereMap.jpg");

pView->setBackground(backgroundId);

管理环境背景的图像路径

要显示图像背景，请设置加载图像的文件路径。使用 OdTvGsViewEnvironmentBackground::setEnvironmentImageFileName 方法指定要加载的路径和文件名（带扩展名）。您还可以使用 OdTvGsViewEnvironmentBackground::getEnvironmentImageFileName 方法获取加载图像的文件路径。


// OdTvResult OdTvGsViewEnvironmentBackground::setEnvironmentImageFileName(const OdString& sFileName)
rc = pBackground->setEnvironmentImageFileName("D:\\Files\\VIS-2717\\FjaderholmarnaSphereMap.jpg");

// OdString OdTvGsViewEnvironmentBackground::getEnvironmentImageFileName(OdTvResult* rc = NULL) const
OdString environmentFileName = pBackground->getEnvironmentImageFileName(&rc);

设置环境图像后，渲染器可以显示背景。

管理环境经度和纬度

环境背景图像可以围绕两个轴旋转。使用 OdTvGsViewEnvironmentBackground::setLongitude 和 OdTvGsViewEnvironmentBackground::setLatitude 方法设置背景经度和纬度。OdTvGsViewEnvironmentBackground 类还具有用于检索这些参数的 getter。这些参数的范围是无限的，但可见结果在 [-OdaPi .. +OdaPi] 范围内，其中 -OdaPi 表示一个方向的 180 度旋转，0 表示不旋转，+OdaPi 表示另一个方向的 180 度旋转。默认情况下，经度和纬度设置为 0。


// OdTvResult OdTvGsViewEnvironmentBackground::setLatitude(double dLatitude)
rc = pBackground->setLatitude(OdaPI2);

// OdTvResult OdTvGsViewEnvironmentBackground::setLongitude(double dLongitude)
rc = pBackground->setLongitude(OdaPI4);