Configure class subsection

The class subsection specifies the default values for window properties.

Windows must be associated with a display. Therefore, include this section in your configuration file only if your system supports displays, or if there are applications on your system that require them. This class section must begin with begin class class_name and end with end class.

The class subsection is used to set default values for the window properties defined within the section; these properties are specified through parameters applied to framebuffers and application windows.

Framebuffers

The number of class subsections that can be defined for framebuffers depends on the number of displays available. Screen allows one framebuffer per display.

You can use the following convention to specify that a class subsection is used for a framebuffer:

     framebufferunique_string
    

The class_name of the class subsection must start with the string framebuffer, then followed by a unique string to identify the class. For example, some valid class name strings are:

Below is an example of using multiple class subsections to specify default values for two framebuffers, each for a specific pipeline:
begin class framebuffer1
   display = 1
   pipeline = 1
   format = rgba8888
   usage = pvr2d
   id_string = fb1
end class

begin class framebuffer2
   display = 2
   pipeline = 2
   format = rgba8888
   usage = pvr2d
   id_string = fb2
end class
       

Application windows

There's no explicit limit on the number of class subsections that can be defined for configuring application windows.

The class_name of the class subsection must be a unique string. This string must also match the window property, SCREEN_PROPERTY_CLASS, that you set in your application.

Below is an example of using a class subsection to specify defaults for an application window:
begin class my_app_properties
  visible = true
  surface-size = 640x480
  source-position = 0,0
  source-size = 640x480
  window-position = 0,0
  window-size = 640x480
end class
        

If you use the above class subsection in your configuration file, then you need to set the SCREEN_PROPERTY_CLASS window property in your application code. The setting of this property triggers Screen to apply the configured values that are associated with that class to your application window.

For example, if you use the above class section in your configuration file, you can use this in your application code:
...
const char *my_win_class = "my_app_properties";
screen_set_window_property_cv(screen_win, SCREEN_PROPERTY_CLASS, strlen(my_win_class), my_win_class);
...
      

instead of this:

...
const int visible = 1
const int buffer_size[2] = { 640, 480};
const int src_pos[2] = { 0, 0};
const int src_size[2] = { 640, 480};
const int win_pos[2] = { 0, 0};
const int win_size[2] = { 640, 480};
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_VISIBLE, &visible);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_BUFFER_SIZE, buffer_size);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SOURCE_POSITION, src_pos);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SOURCE_SIZE, src_size);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_POSITION, win_pos);
screen_set_window_property_iv(screen_win, SCREEN_PROPERTY_SIZE, win_size);
...
   

to set your window properties.

Note:

Properties that can be set only when SCREEN_PROPERTY_SELF_LAYOUT has been enabled are referred to as layout-related properties. These properties (and the SCREEN_PROPERTY_SELF_LAYOUT property) of application windows are set by their manager. See SCREEN_PROPERTY_SELF_LAYOUT from Screen property types for more information on layout-related properties.

Application windows can set their layout-related properties only in the following cases:

  • if there isn't a manager on the system, or
  • if the manager has enabled the SCREEN_PROPERTY_SELF_LAYOUT for those application windows.

However, when applications windows set their SCREEN_PROPERTY_CLASS property using a predefined class from graphics.conf, all the properties configured in that predefined class are applied.

From the above example, the class, "my_app_properties", configures (among others) the following parameters:

  • visible
  • window-position
  • window-size

These parameters change layout-related properties. In this case, they're configured in a predefined class ("my_app_properties") in graphics.conf. Therefore, they're applied when, at runtime, the application window sets its SCREEN_PROPERTY_CLASS property to "my_app_properties".

If there is a manager running on the system, it will be notified of these property changes.

Parameters

The following are valid parameters that can be configured under the class subsection:

Parameter Description Type Possible value(s)
alpha-mode The method of alpha blending to use for alpha compositing. String
non-pre-multiplied (default)
Uses straight RGBA pixel value. For example, (0, 1, 0, 0.5) is green with 100% intensity and 50% opacity
pre-multiplied
Uses pre-multiplied RGBA pixel value. For example, a non-pre-multiplied value of (0, 1, 0, 0.5) can be interpreted as (0, 1, 0) * 0.5, giving a pre-multiplied value of (0, 0.5, 0, 0.5), where 0.5 is green with 100% intensity and 50% opacity
brightness The brightness of a window. This configuration depends on the hardware. That is, the brightness can be configured, but whether or not it takes effect is determined by your hardware. Integer -255 to 255
buffer-count The number of buffers that are to be created or attached to a window. Beyond configuration, you can't set the buffer count; you can only query it. There's no explicit limit for this count. The default is 3. Long Integer 0 to 4294967295

Example: 3

cbabc Content-based automatic brightness control; specifies the content type of a window. This configuration depends on the hardware. That is, cbabc can be configured, but whether or not it takes effect is determined by your hardware. String

none

video

ui

photo

clip-position The x- and y- position of a clipped rectangular viewport within the window buffers. This configuration must be in the form x-position,y-position. Integer 0 to 4294967295, 0 to 4294967295

Example:100,100

clip-size The width and height (in pixels) of a clipped rectangular viewport within the window buffers. This configuration must be in the form widthxheight. Integer 0 to 4294967295 x 0 to 4294967295

Example: 100x100

color The background color of a window. Use RGB color code (HEX value) to identify the color. (e.g., blue = 0xff). unsigned long integer (hex) 0x00 (default: black)
contrast The contrast adjustment of a window. This configuration depends on the hardware; it can be configured, but may or may not take effect as determined by your hardware. Integer -128 to 127
display The connection type to the display or the display on which the window will be shown. If the configuration is an integer, Screen interprets it as the ID of the display. Otherwise, if the configuration is a string that matches one of the valid display connection types, then Screen interprets the string as the display connection type. String or integer

internal

composite

svideo

YPbPr

rgb

rgbhv

dvi

hdmi

1..2

format The pixel format used by a window. Only one format is expected; this format must be supported by the display. String

byte (default)

rgba4444

rgbx4444

rgba5551

rgbx5111

rgb565

rgb888

rgba8888

rgbx8888

yvu9

yuv420

nv12

yv12

uyvy

yuy2

v422

ayuv

global-alpha The global alpha mode to apply to a window Integer 0 to 225
hue The hue adjustment of a window Integer -128 to 127
id_string A string to identify the contents of a window String  
interval The minimum number of vsync periods between posts Unsigned long integer 0 to 4294967295
order The z-order of a window. It's the distance from the bottom that's used when ordering windows and window groups amongst each other. Long integer –2,147,483,648 to 2,147,483,647
permissions The permissions applied to a window. You can set multiple permissions by separating each valid permission by a comma. See "Permissions and Privileges" for valid permission strings. String
pipeline The pipeline identifier. This must refer to a pipeline defined in the wfd device section of the configuration file and depends on the board you are using. Unsigned long integer 1 to 3 are valid values
rotation The clockwise rotation, in degrees, of a window. Window rotation is absolute. Long integer

0

90

180

270

saturation The saturation adjustment of a window Integer -128 to 127
source-position The x and y coordinates of the top-left corner of a rectangular region within the window buffer that represents the source viewport of a window. This is the portion of the window buffer that's to be displayed. This configuration must be in the form x-position,y-position. Integer 0 to 4294967295, 0 to 4294967295

For example: 100, 100

source-size The width and height (in pixels) of a region within the window buffer that represents the source viewport of the window. This is the portion of the window buffer that's to be displayed. This configuration must be in the form widthxheight. Integer 0 to 4294967295 x 0 to 4294967295

For example: 100x100

static The indicator of whether the contents of a window are expected to change Unsigned long integer
0
Window content isn't static.
1
Window content is static.
surface-size The width and height of the window buffer. This configuration must be in the form widthxheight. Integer 0 to 4294967295 x 0 to 4294967295

For example: 100x100

usage
The intended usage for the window buffers and/or the composition module ( the module used for composition onto a framebuffer). You can configure this parameter using any combination of the following:
  • one or more integers representing a valid usage bit

    The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter. Refer to Screen usage flag types for a complete listing of valid usage flags.

  • one or more strings representing a valid usage bit

    Valid strings that are used to represent valid usage bits are:
    • gles1
    • gles2
    • gles3
    • native
    • rotation
    • sw
    • vg
    The resulting usage applied to the window buffers is the bitwise OR of all the valid usage flags configured with this parameter.
  • the name of the user-provided composition module

    When this configuration consists of a string that doesn't match to any valid usage bits, as a string, (see above), Screen interprets this string as the name of the composition module to use.

    The string you use to identify the composition module must be less than 21 characters in length and must not be all digits. Screen uses the follwing algorithm to determine the composition module to load:

    "screen-" + <user-provided composition module> + ".so"

    Note: This parameter differs from the blitter specified in the blit-config parameter under your globals section in graphics.conf. The blitter specified in the blit-config parameter is the blitter that Screen uses when your application explicitly calls the native blit API functions ( screen_blit() and screen_fill() ).

How you configure this usage parmeter has implications on the composition module that Screen loads and uses:

screen-sw.so
The composition module that's used if at least one of the following is set:
  • sw
  • 2 (SCREEN_USAGE_READ)
  • 4 (SCREEN_USAGE_WRITE)
screen-gles1.so
The composition module that's used if at least one of the following is set:
  • gles1
  • 16 (SCREEN_USAGE_OPENGL_ES1)
screen-gles2.so
The composition module that's used if at least one of the following is set:
  • gles2
  • 32 (SCREEN_USAGE_OPENGL_ES2)
screen-vg.so
The composition module that's used if at least one of the following is set:
  • vg
  • 64 (SCREEN_USAGE_OPENVG)
When multiple usage flags are configured, each flag in the configuration must be separated by a comma or space. You can combine the composition module name with the usage flags in the same configuration line as long as they're separated by a comma or a space. For example, the following are examples of valid entries for configuring usage:
  • usage = pvr2d
  • usage = sw native
  • usage = 2 4 8
When multiple usage flags that imply composition modules are set, Screen determines the composition module based on the following priorities (from highest to lowest):
  • screen-sw.so
  • screen-user-provided composition module.so
  • screen-gles1.so
  • screen-gles2.so
  • screen-vg.so
For example, if your usage configuration is: usage = gles1 2 pvr2d, you're specifying a user-provided composition module pvr2d, as well as setting the following usage flags:
  • SCREEN_USAGE_OPENGL_ES1
  • SCREEN_USAGE_READ
Screen loads screen-sw.so as the composition module according to its priorites. Although the user-provided composition module (screen-pvr2d.so) takes precedence over the gles1 module (screen-gles1.so), the usage flag SCREEN_USAGE_READ is set. This flag causes Screen to use the screen-sw.so composition module—which has an even higher priority than the user-provided composition module.
String
gles1
OpenGL ES 1.X is used for rendering the buffer(s) associated with the window
gles2
OpenGL ES 2.X is used for rendering the buffer(s) associated with the window
gles3
OpenGL ES 3.X is used for rendering the buffer(s) associated with the window
native
Buffer(s) associated with the window can be used for native API operations. For example, if your application explicitly calls ( screen_blit() and/or screen_fill()), then this flag must be set.
rotation
Buffer(s) associated with the window can be reconfigured from landscape to portrait orientation without having the need for reallocation.
sw
Buffer(s) associated with the window can be read from and written to.
vg
OpenVG is used for rendering the buffer(s) associated with the window
visible The indicator of whether or not a window is visible String

true (visible)

false (not visible)

window-position The x and y positions of the window screen coordinates. Remember that the position of child and embedded windows are relative to the parent window. For example, if the position of the application window is (10, 10) and the position of the child window is (10, 10), then the position of the child window on the screen is actually (20, 20). This configuration must be in the form x-position,y-position. Integer 0 to 4294967295, 0 to 4294967295

For example:10,10

window-size The width and height (in pixels) of a window. This configuration must be in the form widthxheight. Integer 0 to 4294967295 x 0 to 4294967295

For example: 100x100