# Graphics - [Introduction](#section1333751883213) - [Directory Structure](#section1882912343) - [Constraints](#section68982123611) - [Compilation and Building](#section671864110372) - [Available APIs](#section197399520386) - [WindowManager](#section5851104093816) - [Window](#section3483122273912) - [SubWindow](#section96481249183913) - [Surface](#section12366161544010) - [SurfaceBuffer](#section12001640184711) - [VsyncHelper](#section1392116294211) - [Usage](#section18359134910422) - [Transferring a Producer Surface](#section193464304411) - [Creating a Producer Surface](#section1276823075112) - [Producing a SurfaceBuffer](#section614545716513) - [Consuming a SurfaceBuffer](#section315285412535) - [Adding Custom Data to a SurfaceBuffer](#section612412125616) - [Registering a Vsync Callback Listener](#section1148115214576) - [\#EN-US\_TOPIC\_0000001105482134/section1939493174420](#section1939493174420) - [Repositories Involved](#section6488145313) ## Introduction The Graphics subsystem provides graphics and window management capabilities, which can be invoked by using Java or JS APIs. It can be used for UI development for all standard-system devices. The following figure shows the architecture of the Graphics subsystem. ![](figures/graphic.png) - Surface Provides APIs for managing the graphics buffer and the efficient and convenient rotation buffer. - Vsync Provides APIs for managing registration and response of all vertical sync signals. - WindowManager Provides APIs for creating and managing windows. - WaylandProtocols Provides the communication protocols between the window manager and synthesizer. - Compositor Implements synthesis of layers. - Renderer Functions as the back-end rendering module of the synthesizer. - Wayland protocols Provides Wayland inter-process communication protocols. - Shell Provides multi-window capabilities. - Input Manger Functions as the multimodal input module that receives input events. ## Directory Structure ``` foundation/graphic/standard/ ├── frameworks # Framework code │ ├── bootanimation # Boot Animation code │ ├── surface # Surface code │ ├── vsync # Vsync code │ └── wm # WindowManager code ├── interfaces # External APIs │ ├── innerkits # Native APIs │ └── kits # JS APIs and NAPIs └── utils # Utilities ``` ## Constraints - Language version: C++ 11 or later ## Compilation and Building The dependent APIs include the following: - graphic\_standard:libwms\_client - graphic\_standard:libsurface - graphic\_standard:libvsync\_client ## Available APIs ### WindowManager

API

Description

GetInstance

Obtains the pointer to a singleton WindowManager instance.

GetMaxWidth

Obtains the width of the screen.

GetMaxHeight

Obtains the height of the screen.

CreateWindow

Creates a standard window.

CreateSubWindow

Creates a child window.

StartShotScreen

Takes a screenshot.

StartShotWindow

Captures a window.

SwitchTop

Moves the specified window to the top.
### Window

API

Description

Show

Displays the current window.

Hide

Hides the current window.

Move

Moves the current window to a specified position.

SwitchTop

Moves the current window to the top.

ChangeWindowType

Changes the type of the current window.

ReSize

Resizes the current window.

Rotate

Rotates the current window.
### SubWindow

API

Description

Move

Moves the current child window.

SetSubWindowSize

Sets the size of the current child window.
### Surface

API

Description

CreateSurfaceAsConsumer

Creates a surface for the buffer consumer.

CreateSurfaceAsProducer

Creates a surface for the buffer producer. Only production-related APIs can be used.

GetProducer

Obtains an internal IBufferProducer object of Surface.

RequestBuffer

Requests a SurfaceBuffer object to be produced.

CancelBuffer

Cancels a SurfaceBuffer object to be produced.

FlushBuffer

Flushes a produced SurfaceBuffer object with certain information.

AcquireBuffer

Requests a SurfaceBuffer object to be consumed.

ReleaseBuffer

Returns a consumed SurfaceBuffer object.

GetQueueSize

Obtains the number of concurrent buffers.

SetQueueSize

Sets the number of concurrent buffers.

SetDefaultWidthAndHeight

Sets the default width and height.

GetDefaultWidth

Obtains the default width.

GetDefaultHeight

Obtains the default height.

SetUserData

Stores string data, which will not be transferred through IPC.

GetUserData

Obtains string data.

RegisterConsumerListener

Registers a consumer listener to listen for buffer flush events.

UnregisterConsumerListener

Unregiseters a consumer listener.
### SurfaceBuffer

API

Description

GetBufferHandle

Obtains the BufferHandle pointer to the SurfaceBuffer object.

GetWidth

Obtains the width of the SurfaceBuffer object.

GetHeight

Obtains the height of the SurfaceBuffer object.

GetFormat

Obtains the color format of the SurfaceBuffer object.

GetUsage

Obtains the usage of the SurfaceBuffer object.

GetPhyAddr

Obtains the physical address of the SurfaceBuffer object.

GetKey

Obtains the key of the SurfaceBuffer object.

GetVirAddr

Obtains the virtual address of the SurfaceBuffer object.

GetSize

Obtains the size of the SurfaceBuffer object.

SetInt32

Sets the 32-bit integer for the SurfaceBuffer object.

GetInt32

Obtains the 32-bit integer for the SurfaceBuffer object.

SetInt64

Sets the 64-bit integer for the SurfaceBuffer object.

GetInt64

Obtains the 64-bit integer for the SurfaceBuffer object.
### VsyncHelper

API

Description

Current

Obtains the VsyncHelper object of the current runner.

VsyncHelper

Constructs a VsyncHelper object using an EventHandler object.

RequestFrameCallback

Registers a frame callback.
## Usage ### Transferring a Producer Surface 1. Named service - Service registration: ``` // Obtain a consumer surface. sptr surface = Surface::CreateSurfaceAsConsumer(); // Extract the producer object. sptr producer = surface->GetProducer(); // Register the service. auto sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); sm->AddSystemAbility(IPC_SA_ID, producer->AsObject()); ``` - Construction of a producer surface: ``` // Obtain a producer object. auto sm = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager(); sptr robj = sm->GetSystemAbility(IPC_SA_ID); // Construct a surface. sptr bp = iface_cast(robj); sptr surface = Surface::CreateSurfaceAsProducer(bp); ``` 2. Anonymous service - Sending of a surface: ``` // Obtain a consumer surface. sptr surface = CreateSurfaceAsConsumer(); // Extract the producer object. sptr producer = surface->GetProducer(); // Return the producer object to the client. parcel.WriteRemoteObject(producer); ``` ### Creating a Producer Surface ``` // Obtain a producer object. sptr remoteObject = parcel.ReadRemoteObject(); // Construct a surface. sptr bp = iface_cast(robj); sptr surface = Surface::CreateSurfaceAsProducer(bp); ``` ### Producing a SurfaceBuffer ``` // Prerequisite: a producer surface BufferRequestConfig requestConfig = { .width = 1920, // Screen width .height = 1080, // Screen height .strideAlignment = 8, // Stride alignment byte .format = PIXEL_FMT_RGBA_8888, // Color format .usage = HBM_USE_CPU_READ | HBM_USE_CPU_WRITE | HBM_USE_MEM_DMA, // Usage .timeout = 0, // Delay }; sptr buffer; int32_t releaseFence; GSError ret = surface->RequestBuffer(buffer, releaseFence, requestConfig); if (ret != GSERROR_OK) { // failed } BufferFlushConfig flushConfig = { .damage = { // Redrawing buffer zone .x = 0, // Horizontal coordinate of the start point .y = 0, // Vertical coordinate of the start point .w = buffer->GetWidth(), // Width of the buffer zone .h = buffer->GetHeight(), // Height of the buffer zone }, .timestamp = 0 // Time displayed to consumers. Value 0 indicates the current time. }; ret = surface->FlushBuffer(buffer, -1, flushConfig); if (ret != GSERROR_OK) { // failed } ``` ### Consuming a SurfaceBuffer ``` // Prerequisite: a consumer surface class TestConsumerListener : public IBufferConsumerListener { public: void OnBufferAvailable() override { sptr buffer; int32_t flushFence; GSError ret = surface->AcquireBuffer(buffer, flushFence, timestamp, damage); if (ret != GSERROR_OK) { // failed } // ... ret = surface->ReleaseBuffer(buffer, -1); if (ret != GSERROR_OK) { // failed } } }; sptr listener = new TestConsumerListener(); GSError ret = surface->RegisterConsumerListener(listener); if (ret != GSERROR_OK) { // failed } ``` ### Adding Custom Data to a SurfaceBuffer ``` sptr buffer; GSError ret = buffer->SetInt32(1, 3); if (ret != GSERROR_OK) { // failed } int32_t val; ret = buffer->GetInt32(1, val); if (ret != GSERROR_OK) { // failed } ``` ### Registering a Vsync Callback Listener 1. Construct a **VsyncHelper** object using **handler**. ``` auto runner = AppExecFwk::EventRunner::Create(true); auto handler = std::make_shared(runner); auto helper = new VsyncHelper(handler); runner->Run(); struct FrameCallback cb = { .timestamp_ = 0, .userdata_ = nullptr, .callback_ = [](int64_t timestamp, void* userdata) { }, }; GSError ret = helper->RequestFrameCallback(cb); if (ret != GSERROR_OK) { // failed } ``` 2. Use **Current** in **handler**. ``` auto runner = AppExecFwk::EventRunner::Create(true); auto handler = std::make_shared(runner); handler->PostTask([]() { auto helper = VsyncHelper::Current(); struct FrameCallback cb = { .timestamp_ = 0, .userdata_ = nullptr, .callback_ = [](int64_t timestamp, void* userdata) { }, }; GSError ret = helper->RequestFrameCallback(cb); if (ret != GSERROR_OK) { // failed } }); runner->Run(); ``` ## Repositories Involved Graphics subsystem **graphic\_standard** ace\_ace\_engine aafwk\_L2 multimedia\_media\_standard multimedia\_camera\_standard