Broadcom Nexus学习 （一） Graphics,Display
0. Broadcom Nexus介绍：
Nexus是Broadcom提供的一套开发中间件，以标准API形式为Digital TV 和Set-Top boxes上层程序提供标准接口，它将不同的底层与上层开发隔绝开来，以达到上层开发与底层无关的目的。所有Interface的用法和思路基本上是一致的。Sam最先接触到的Nexus模块就是 Graphics.
1. Nexus Platform 接口和初始化：
Nexus有个API初始化各个模块以及硬件（NEXUS_Platform_Init（））。应用程序也可以利用其参数定制初始化哪些模块以及动作。通常使用NEXUS_Platform_GetDefaultSettings()得到缺省的setting.修改想要修改的内容，之后再调用NEXUS_Platform_Init()初始化Platform.
NEXUS_PlatformSettings platformSettings;
NEXUS_Platform_GetDefaultSettings(&platformSettings);
//.... 修改必要的设置
NEXUS_Platform_Init(&platformSettings);
NEXUS_PlatformSettings结构体中可选择的选项通常有：I2C channel是否打开，是否FPGA channel打开，是否打开output等。
NEXUS_Platform_Init()会自动地打开和配置Interface.（如各种output等）。应用程序不应该再次去打开它，而是使用NEXUS_Platform_GetConfiguration()重新得到Handle.
NEXUS_PlatformConfiguration platformConfiguration;
NEXUS_Platform_GetConfiguration(&platformConfiguration);
NEXUS_PlatformConfiguration结构体包含如下内容：
NEXUS_I2cHandle i2c[NEXUS_NUM_I2C_CHANNELS]; //I2C channel.
我们通常最关心的是output Handle,
struct {
NEXUS_ComponentOutputHandle component[NEXUS_NUM_COMPONENT_OUTPUTS];
NEXUS_CompositeOutputHandle composite[NEXUS_NUM_COMPOSITE_OUTPUTS];
NEXUS_RfmHandle rfm[NEXUS_NUM_RFM_OUTPUTS];
NEXUS_SvideoOutputHandle svideo[NEXUS_NUM_SVIDEO_OUTPUTS];
NEXUS_AudioDacHandle audioDacs[NEXUS_NUM_AUDIO_DACS];
NEXUS_SpdifOutputHandle spdif[NEXUS_NUM_SPDIF_OUTPUTS];
NEXUS_I2sOutputHandle i2s[NEXUS_NUM_I2S_OUTPUTS];
NEXUS_HdmiOutputHandle hdmi[NEXUS_NUM_HDMI_OUTPUTS];
NEXUS_Ccir656OutputHandle ccir656[NEXUS_NUM_656_OUTPUTS];
} outputs;
分量，混合和Svideo output handle就在其中。
2. Graphics 具体讲解：
Nexus graphics 包含几个Interface. 各个Interface各自提供一些能力，应用程序可以将它们组合起来使用。
Interface包含如下：
Display: 是Graphics模块的核心，它指定哪个surface为framebuffer(当前显示的)。指定哪几个output会输出（composite,svideo等），以及如何将framebuffer合成到video上。
Surface: 其实就是一块内存。创建Surface时用参数指定:width, height, pitch, pixel format。长度x宽度x每个象素的长度就决定了Surface大小。可创建surface的个数限制与分配给Nexus的堆大小。
Graphics2D: 提供从一块surface blit(整块copy)到另一块surface的能力。提供填充一块surface 使用某种颜色和Alpha的能力。
Graphics3D: 提供适配一个3D graphics到Surface的能力。
VideoImageInput:Route graphics through the video feeder hardware (MFD)
2.1. Surface的创建(NEXUS_Surface_Create)：
Surface创建使用NEXUS_Surface_Create创建。Surface的长度，宽度，深度，pixel format则可以由参数决定。
具体过程如下：
NEXUS_SurfaceHandle surface;
NEXUS_SurfaceCreateSettings createSettings;
NEXUS_Surface_GetDefaultCreateSettings(&createSettings);
createSettings.pixelFormat = NEXUS_PixelFormat_eA8_R8_G8_B8;
createSettings.width = 720;
createSettings.height = 480;
surface = NEXUS_Surface_Create(&createSettings);
NEXUS_SurfaceCreateSettings：结构体中包含了Surface的一些关键点：象素格式，调色板格式，surface长度，宽度。倾斜度（缺省为：象素长度x宽度，也就是每行的字节数）
2.2：Display的建立和配置：
2.2.1: Display的创建：
与Surface创建相同，Display创建时，也需要参数来指定Display的创建模式。
NEXUS_DisplaySettings displaySettings;
NEXUS_DisplayHandle display;
NEXUS_Display_GetDefaultSettings(&displaySettings);
displaySettings.format = NEXUS_VideoFormat_eNtsc;
display = NEXUS_Display_Open(0, &displaySettings);
NEXUS_DisplaySettings 结构体中包含Display的一些选项。其中format表明此Display将要输出的制式。它决定了TV中显示的宽，高。
2.2.2：Display显示输出channel的配置：
如前所述，在Platform初始化时，Output Interface已经被打开。此时需要得到它们的Handle. 给Display添加Output .
NEXUS_PlatformConfiguration platformConfig;
NEXUS_Platform_GetConfiguration(&platformConfig);
NEXUS_Display_AddOutput(display, NEXUS_ComponentOutput_GetConnector(platformConfig.outputs.component[0]));
NEXUS_Display_AddOutput(display, NEXUS_CompositeOutput_GetConnector(platformConfig.outputs.composite[0]));
此处Display添加了分量和混合2种输出。
2.2.3：Display Frame buffer的指定：
只有将某个Surface指定为Frame buffer, Surface中的内容才会按格式和设置显示到TV上。所以应用程序可以创建2-3个surface,轮流指定为Frame Buffer来加快速度。
NEXUS_Display_SetGraphicsFramebuffer(display, surface);
3. Graphics2D的建立和使用：
3.1：Graphics2D的建立：
Graphics2D的建立与其它Interface相同，需要参数指定Graphics2D的特征。
NEXUS_Graphics2DHandle gfx;
NEXUS_Graphics2DOpenSettings openSettings;
openSettings.preAllocPacketMemory = true; //if maxOperations is non-zero, this must be true.
openSettings.maxOperations = 100; //同步，异步blit的最大次数。如果是异步blit，则需要在blit次数超此次数之前使用NEXUS_Graphics2D_Checkpoint（）。
gfx = NEXUS_Graphics2D_Open(0, &openSettings);
3.3: Graphics2D Setting:
NEXUS_Graphics2DSettings gfxSettings;
NEXUS_Graphics2D_GetSettings(gfx, &gfxSettings);
gfxSettings.checkpointCallback.callback = complete;
gfxSettings.checkpointCallback.context = event;
NEXUS_Graphics2D_SetSettings(gfx, &gfxSettings);
NEXUS_Graphics2DSettings比较重要的参数有：
bool blockedSync; //如果为true,则所有fill,blit会阻塞直到动作完成。（只有简单的程序会这么用）
此时，不需要NEXUS_Graphics2D_Checkpoint。
如果为false,则fill,blit不会被阻塞。所以需要NEXUS_Graphics2D_Checkpoint（）来检测fill或blit动作是否已经完成。
NEXUS_CallbackDesc checkpointCallback; 在异步时使用，NEXUS_Graphics2D_Checkpoint（）会调用它的callback。第一个参数为context.
callback function通常的处理是：BKNI_SetEvent()，发送一个event.
3.4：Graphics2D Fill:
在使用Fill功能时，需要先指定Surface. fill的颜色，Fill Surface的区域，color和alpha方式等。
NEXUS_Graphics2D_GetDefaultFillSettings(&fillSettings);
fillSettings.surface = framebuffer; //指定surface.
fillSettings.rect.width = createSettings.width; //如果要fill整个surface. x,y=0. width,height与surface宽高相同。
fillSettings.rect.height = createSettings.height;
fillSettings.color = 0; //色彩方式
NEXUS_Graphics2D_Fill(gfx, &fillSettings);
如果为异步方式（3.3中讲过），Fill后，必须加上NEXUS_Graphics2D_Checkpoint(gfx, NULL); 以确认Fill动作已真的完成。
注意：此处NEXUS_Graphics2D_Checkpoint(gfx, NULL); 只是察看Graphics Hardware是否正在Blit或Fill. 如果返回值为Success.表明当前硬件没有Blit或Fill. 如果返NEXUS_GRAPHICS2D_QUEUED,泽表明此时有Fill或Blit在排队。此时，则当Blit或Fill完成时，NEXUS_Graphics2DSettings::checkpointCallback 会被调用。
如3.3所讲，NEXUS_Graphics2D_Checkpoint()如果返回Success,则表明Fill完成，如果返回NEXUS_GRAPHICS2D_QUEUED，则在Fill动作完成后，自动调用callback function. Callback function又发送了一个event. 所以可以在NEXUS_Graphics2D_Checkpoint(gfx, NULL); 后添加:
BKNI_WaitForEvent();来确认Fill动作的完成。
3.5： Graphics2D Blit:
与其它动作类似，Blit也需要得到setting. 并设置想要blit的源sruface和目标surface. 以及各自的区域。
NEXUS_Graphics2DBlitSettings blitSettings;
NEXUS_Graphics2D_GetDefaultBlitSettings(&blitSettings);
blitSettings.source.surface = surface;
blitSettings.source.rect.x = 0;
blitSettings.source.rect.y = 0;
blitSettings.source.rect.width = 100;
blitSettings.source.rect.height = 140;
blitSettings.output.surface = surface;
blitSettings.output.rect.x = (rand() % (createSettings.width-120)) + 100;
blitSettings.output.rect.y = (rand() % (createSettings.height-20));
blitSettings.output.rect.width = 20;
blitSettings.output.rect.height = 20;
blitSettings.colorOp = NEXUS_BlitColorOp_eCopySource;
blitSettings.alphaOp = NEXUS_BlitAlphaOp_eCopySource;
rc = NEXUS_Graphics2D_Blit(gfx, &blitSettings);
4. Surface的长度，宽度的决定：
看到这个条目，可能会觉得有些奇怪，Surface的长宽，不是由自己指定的吗。呵呵，其实Sam的意思是决定Surface长宽的因素总结。
Surface如果想全屏显示于Display当前的video format下。则需要与video format长宽相同。
NEXUS_VideoFormat_GetInfo(displaySettings.format, &videoFormatInfo); //从display video 取出信息
createSettings.pixelFormat = NEXUS_PixelFormat_eA8_R8_G8_B8;
createSettings.width = videoFormatInfo.width; //讲长度宽度设置为与video format相同
createSettings.height = videoFormatInfo.height;
surface = NEXUS_Surface_Create(&createSettings);
还有一种情况比较特殊，下一节统一讲。
5.Display 如何放置Graphics Frame buffer于Video Window相关知识：
Display可以指定某个Surface为Graphics Frame buffer.但是Surface是否要全部显示，以及显示在TV屏幕的哪个位置，这是可设定的。下面就详细分析这个议题。
首先，有4个宽高值需要注意：
1. VideoWindow的宽高。
2. GraphicsFramebuffer的宽高。
3. Surface的宽高。
4. Display video format的宽高。
Display的video format决定了TV屏幕的大小，也就是VideoWindow的大小。所以Sam认为Dispaly Video format的宽高等同于VideoWindow的宽高。
GraphicsFramebuffer的大小应该是个虚值，可能与它指定的Surface相同。
Surface的大小可以自己定义，但哪一部份显示则由Display指定。
结构体NEXUS_GraphicsSettings中的值决定了Display如何将Graphics Frame buffer匹配于VideoWindow.也就是说将Graphics Frame Buffer如何放置于TV 屏幕。放置在什么位置，显示哪一部份Frame buffer内容等等。（所以前面说surface指定为framebuffer并不意味着它能全部显示）
NEXUS_Rect position;
NEXUS_Rect clip;
NEXUS_Rect结构体是个矩形，x,y表示左上角位置:
typedef struct NEXUS_Rect
{
int16_t x;
int16_t y;
uint16_t width;
uint16_t height;
} NEXUS_Rect;
position: 顾名思义，是说Display中Surface显示的部分。换句话说，Video Window(TV屏幕)的这一部分用来显示Framebuffer(Surface).
clip: Surface 中想要显示的部分。
当Display想要将surface显示于一个Video Window时，其实是将Surface中clip部分显示于Video window的Position部分。
我们会很快想到，如果position与clip大小不同怎么办？
当clip的宽度小于position的宽度时（高度相同），会将其水平拉伸。
当clip的高度小于position时（宽度相同），则无法显示。
当clip的宽度大于position的宽度时，则只显示一部分。
当clip的高度大于position的高度时，则只显示position部分。