Graphics

• Introduction

• Directory Structure

• Constraints

• Compilation and Building

• Available APIs

  • WindowManager
  • Window
  • SubWindow
  • Surface
  • SurfaceBuffer
  • VsyncHelper

• Usage

  • Transferring a Producer Surface
  • Creating a Producer Surface
  • Producing a SurfaceBuffer
  • Consuming a SurfaceBuffer
  • Adding Custom Data to a SurfaceBuffer
  • Registering a Vsync Callback Listener

• #EN-US_TOPIC_0000001105482134/section1939493174420

• Repositories Involved

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.

• 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 = Surface::CreateSurfaceAsConsumer();
     // Extract the producer object.
     sptr<IBufferProducer> 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<IRemoteObject> robj = sm->GetSystemAbility(IPC_SA_ID);
     // Construct a surface.
     sptr<IBufferProducer> bp = iface_cast<IBufferProducer>(robj);
     sptr<Surface> surface = Surface::CreateSurfaceAsProducer(bp);
     

2. Anonymous service

   • Sending of a surface:

     // Obtain a consumer surface.
     sptr<Surface> surface = CreateSurfaceAsConsumer();
     // Extract the producer object.
     sptr<IRemoteObject> producer = surface->GetProducer();
     // Return the producer object to the client.
     parcel.WriteRemoteObject(producer);
     

Creating a Producer Surface

// Obtain a producer object.
sptr<IRemoteObject> remoteObject = parcel.ReadRemoteObject();
// Construct a surface.
sptr<IBufferProducer> bp = iface_cast<IBufferProducer>(robj);
sptr<Surface> 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<SurfaceBuffer> 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<SurfaceBuffer> 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<IBufferConsumerListener> listener = new TestConsumerListener();
GSError ret = surface->RegisterConsumerListener(listener);
if (ret != GSERROR_OK) {
    // failed
}

Adding Custom Data to a SurfaceBuffer

sptr<SurfaceBuffer> 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<AppExecFwk::EventHandler>(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<AppExecFwk::EventHandler>(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