Zakero_Yetani.h File Reference

Zakero Yetani. More...

Include dependency graph for Zakero_Yetani.h:

Go to the source code of this file.

Classes
struct	zakero::Yetani::CursorConfig
	Cursor configuration. More...
struct	zakero::Yetani::Key
	Key event information. More...
struct	zakero::Yetani::KeyModifier
	A collection modifier flags. More...
struct	zakero::Yetani::Window::Memory
	The shared memory. More...
struct	zakero::Yetani::Output
	Information about a output device. More...
struct	zakero::Yetani::PointerAxis
	Information about an Axis event. More...
struct	zakero::Yetani::PointerButton
	Information about a pointer button event. More...
struct	zakero::Yetani::PointMm
	A location that uses millimeters. More...
struct	zakero::Yetani::PointPercent
	A location that uses percentages. More...
struct	zakero::Yetani::PointPixel
	A location that uses pixels. More...
struct	zakero::Yetani::SizeMm
	Size measured in millimeters. More...
struct	zakero::Yetani::SizePercent
	Size measured as a percentage of the Output (Monitor) resolution. More...
struct	zakero::Yetani::SizePixel
	Size measured in pixels. More...
class	zakero::Yetani::Window
	A Window. More...
class	zakero::Yetani
	A wrapper class for Wayland. More...

Macros
#define	ZAKERO_YETANI_ENABLE_DEBUG
	Enable debugging output. More...
#define	ZAKERO_YETANI_ENABLE_DEBUG_STREAM
	The stream to use for debugging output. More...
#define	ZAKERO_YETANI_ENABLE_SAFE_MODE
	Add extra error checking. More...
#define	ZAKERO_YETANI_IMPLEMENTATION
	Activate the implementation code. More...

Functions
bool	zakero::operator== (Yetani::PointMm &lhs, Yetani::PointMm &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Yetani::PointPercent &lhs, Yetani::PointPercent &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Yetani::PointPixel &lhs, Yetani::PointPixel &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Yetani::SizeMm &lhs, Yetani::SizeMm &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Yetani::SizePercent &lhs, Yetani::SizePercent &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Yetani::SizePixel &lhs, Yetani::SizePixel &rhs) noexcept
	Compare two Size objects. More...
std::string	zakero::to_string (const std::error_code &error) noexcept
	Convert an std::error_code to a std::string. More...
std::string	zakero::to_string (const wl_shm_format &shm_format) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::Key &key) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::KeyModifier &key_modifier) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::KeyState &key_state) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::Output &output) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointerAxis &axis) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointerAxisSource &source) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointerAxisType &type) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointerButton &button) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointerButtonState &button_state) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointMm &point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointPercent &point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::PointPixel &point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::SizeMm &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::SizePercent &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::SizePixel &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Yetani::WindowMode &window_mode) noexcept
	Convert a value to a std::string. More...

Detailed Description

API	Dependencies	TL;DR	What Is It?	Why Use It?	How To Use It?	Version

Making the Wayland windowing system easy to use.

Dependencies

• Zakero_Base.h
• Zakero_MemoryPool.h

TL;DR:

This library makes it very easy to connect to Wayland and display windows. The developer must write pixel data directly into the window. No UI or graphics functionality is provided.

To use:

1. Add the implementation to a source code file:

   #define ZAKERO_MEMORYPOOL_IMPLEMENTATION
   #define ZAKERO_YETANI_IMPLEMENTATION
   #include "Zakero_Yetani.h"

2. Add the library to where it is used:

   #include "Zakero_Yetani.h"

3. Link to the Wayland client library and pthread when building:

   -lpthread -lwayland-client

What Is It?

Wayland is a Windowing System and was intended to strip all the cruft that has built up in X11. The part of Wayland that does the rendering is called the "Wayland Compositor". The "Wayland Client" is the application that the user interacts with. Communication between the two is done using the "Wayland Protocol". This is a simplification. If you want more details, please do a search on the internet.

Implementing the "Wayland Protocol" for a "Wayland Client" is easy to do.
However, this code is verbose and tedious. Plus, once you start working on your second and third "Wayland Client", much of this code is duplicated.
Consolidating this redundant code is one of the reasons behind Yetani.

The zakero::Yetani class interacts with the basic Wayland functionality, such as determining what pixel formats are supported and which Output devices are currently available. Custom graphics for cursors is also supported.

The zakero::Yetani::Window class makes creating a window effortless. Rendering graphics has been simplified to the point where you just provide the graphics data to the window and it will take care of the rest. zakero::Yetani::Window also supports sizes in percentages of the output device size as well as in millimeters, in additional to the traditional pixel sizes.

Why Use It?

Wayland was intended to strip all the cruft that has built up in X11 and focus on three things. The part of Wayland that does the rendering is the "Wayland Compositor". The part that is the application is the "Wayland Client". And they talk using the "Wayland Protocol". Again, this is a simplification. If you want more details, please do a search on the internet.

Implementing the "Wayland Protocol" in "Wayland Client" is easy to do.
However, this code is verbose and tedious. Once you start working on your second and third "Wayland Client", much of this code is duplicated.
Consolidating the redundant code is the purpose of the Yetani.

How To Use It?

Step 0

Your compiler must support at least the C++20 standard. The location of the Zakero_*.h header files must be in your compiler's include path.

Step 1

The first step is to select which C++ source code file will contain the Zakero Yetani implementation. Once the location has been determined, add the following to that file:

#define ZAKERO_MEMORYPOOL_IMPLEMENTATION
#define ZAKERO_YETANI_IMPLEMENTATION
#include "Zakero_Yetani.h"

The macro ZAKERO_YETANI_IMPLEMENTATION tells the header file to include the implementation of the Yetani.

Notice that the Zakero MemoryPool implementation, ZAKERO_MEMORYPOLL_IMPLEMENTATION, is included before the Zakero_Yetain.h header. Zakero Yetani depends on the memory pool for shared memory with the Wayland compositor. If the Zakero MemoryPool implementation was added else where, this define can be omitted.

In all other files that will use Yetani, they only need to include the header.

#include "Zakero_Yetani.h"

Step 2

Below is a simple program that will conncet to the Wayland Compositor and display a window.

#define ZAKERO_MEMORYPOOL_IMPLEMENTATION
#define ZAKERO_YETANI_IMPLEMENTATION
#include "Zakero_Yetani.h"
 
int main()
{
     std::error_code error;
 
     zakero::Yetani* yetani = zakero::Yetani::connect(error);
     if(error)
     {
             std::cout << "Error: " << zakero::to_string(error) << '\n';
             return 1;
     }
 
     zakero::Yetani::SizePixel window_size = { 640, 480 };
     auto* window = yetani->windowCreate(window_size, error);
     if(error)
     {
             std::cout << "Error: " << zakero::to_string(error) << '\n';
             return 1;
     }
 
     window->titleSet("Yetani");
 
     bool time_to_die = false;
     window->onCloseRequest([&]()
     {
             time_to_die = true;
     });
 
     while(time_to_die == false)
     {
             std::this_thread::yield();
     }
 
     delete window;
     delete yetani;
 
     return 0;
}

The following commands will build and run the example program.

> g++ -std=c++20 -lpthread -lwayland-client -o example example.cpp
> ./example

Version

v0.6.1

• Moved to_string(std::error_code) to Zakero_Base.h
• Moved equalish() to Zakero_Base.h
• Documentation improvements

v0.6.0

• Fully Documented
• No Known Bugs

v0.5.0

• Cursor Support
• Support many Surfaces

v0.4.0

• Keyboard Input Support (uses Linux Input Event codes)

v0.3.0

• Mouse Input Support

v0.2.0

• Memory Manager for handling dynamic allocations from a single memory pool.

v0.1.0

• Wayland Output device hot-plug support
• Support for many Yetani instances
• Support for many Windows in each Yetani object
• Server Side Decorations support when available
• Window resizing
• Window image/surface rendering
• Fully multi-threaded, all Wayland execution happens in a separate thread.
• Flexible sizing options: Millimeters, Percent, and Pixel

---

Class Documentation

zakero::Yetani::CursorConfig

struct zakero::Yetani::CursorConfig

Class Members
wl_shm_format	format	The pixel format.
int32_t	hotspot_x	The X location of the hotspot.
int32_t	hotspot_y	The Y location of the hotspot.
const vector< void * > &	image_data	A collection of image data.
SizePixel	size	The size of the cursor.
milliseconds	time_per_frame	How long to display each frame of animation.

zakero::Yetani::Key

struct zakero::Yetani::Key

Time is based on the "steady clock" and not system time.

Class Members
uint32_t	code	The key code of the event.
KeyState	state	The state of the key.
uint32_t	time	When the key event happened.

zakero::Yetani::KeyModifier

struct zakero::Yetani::KeyModifier

The meaning of the modifiers are:

• pressed
  This is the easiest to understand type of modifier. A modifier such as "Control" is pressed.
• locked
  The best example of a "locked" modifier is the "Caps Lock" key.
• latched
  This modifer can occur with "Sticky Keys".

Class Members
uint32_t	group	The keyboard layout.
uint32_t	latched	A collection of latched modifiers.
uint32_t	locked	A collection of locked modifiers.
uint32_t	pressed	A collection of pressed modifiers.

zakero::Yetani::Window::Memory

struct zakero::Yetani::Window::Memory

This structure holds the shared memory used by the Window.

Class Members
MemoryPool	memory_pool	The Window's Memory Pool.
struct wl_shm_pool *	wl_shm_pool	A pointer to the Wayland Shared Memory Pool.

zakero::Yetani::Output

struct zakero::Yetani::Output

All the Wayland information about an output device in a single structure.

Class Members
uint32_t	flags	wl_output_mode bitfield properties.
int32_t	height	The height of the device in hardware units.
string	make	Description of the manufacturer.
string	model	Description of the model.
uint32_t	physical_height_mm	The height of the device in millimeters.
uint32_t	physical_width_mm	The width of the device in millimeters.
float	pixels_per_mm_horizontal	A pre-calculated value.
float	pixels_per_mm_vertical	A pre-calculated value.
int32_t	refresh_mHz	The current refresh rate of the device.
int32_t	scale_factor	The scaling factor between the device and compositor.
int32_t	subpixel	The device's subpixel orientation.
int32_t	transform	Transform that maps framebuffer to output.
int32_t	width	The width of the device in hardware units.
int32_t	x	The X position within the global compositor.
int32_t	y	The Y position within the global compositor.

zakero::Yetani::PointerAxis

struct zakero::Yetani::PointerAxis

Class Members
float	distance	The distance traveled.
PointerAxisSource	source	The source of the event.
int32_t	steps	The number of rotation steps.
uint32_t	time	When the event occurred.
PointerAxisType	type	The type of Axis.

zakero::Yetani::PointerButton

struct zakero::Yetani::PointerButton

Class Members
uint32_t	code	The event code.
PointerButtonState	state	The button state.

Macro Definition Documentation

ZAKERO_YETANI_ENABLE_DEBUG

#define ZAKERO_YETANI_ENABLE_DEBUG

Enabled debugging messages to be written.

ZAKERO_YETANI_ENABLE_DEBUG_STREAM

#define ZAKERO_YETANI_ENABLE_DEBUG_STREAM

This macro holds the stream that will be written to for the debug messages.
If this macro is undefined at compile time, then std::cerr will be used.

Example

#define ZAKERO_YETANI_ENABLE_DEBUG_STREAM MyLogger::errorLogStream()

ZAKERO_YETANI_ENABLE_SAFE_MODE

#define ZAKERO_YETANI_ENABLE_SAFE_MODE

Before a method executes, it should validate the argument values that it receives. This is useful while developing code but adds overhead. If the calling code can guarantee that all argument data is valid, this macro can be enabled to reduce the validation checks and overhead.

ZAKERO_YETANI_IMPLEMENTATION

#define ZAKERO_YETANI_IMPLEMENTATION

Defining this macro will cause the Zakero Yetani implementation to be included. This should only be done once, since compiler and/or linker errors will typically be generated if more than a single implementation is found.

Note

It does not matter if the macro is given a value or not, only its existence is checked.

Function Documentation

operator==() [1/6]

bool zakero::operator== ( Yetani::PointMm &  lhs, Yetani::PointMm &  rhs  )

noexcept

The X coordinates of both objects are considered to be equal if they are less than 0.001mm apart.

The same applies with the Y coordinates.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [2/6]

bool zakero::operator== ( Yetani::PointPercent &  lhs, Yetani::PointPercent &  rhs  )

noexcept

The X coordinates of both objects are considered to be equal if they are less than 0.001% apart.

The same applies with the Y coordinates.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [3/6]

bool zakero::operator== ( Yetani::PointPixel &  lhs, Yetani::PointPixel &  rhs  )

noexcept

Compare the X and Y values.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [4/6]

bool zakero::operator== ( Yetani::SizeMm &  lhs, Yetani::SizeMm &  rhs  )

noexcept

The width of both objects are considered to be equal if they are less than 0.001mm difference in length.

The same applies with the height.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [5/6]

bool zakero::operator== ( Yetani::SizePercent &  lhs, Yetani::SizePercent &  rhs  )

noexcept

The width of both objects are considered to be equal if they are less than 0.001% difference in length.

The same applies with the height.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [6/6]

bool zakero::operator== ( Yetani::SizePixel &  lhs, Yetani::SizePixel &  rhs  )

noexcept

Compare the width and height values.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

to_string() [1/18]

std::string zakero::to_string ( const std::error_code &  error )

inlinenoexcept

The provided error will be converted to a string.

Returns

A string

Parameters

error

The value

to_string() [2/18]

std::string zakero::to_string ( const wl_shm_format &  shm_format )

noexcept

The Wayland SHM color format will be converted into a std::string.

Returns

A string

Parameters

shm_format

The value

to_string() [3/18]

std::string zakero::to_string ( const Yetani::Key &  key )

noexcept

The key data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

key

The value

to_string() [4/18]

std::string zakero::to_string ( const Yetani::KeyModifier &  key_modifier )

noexcept

The key_modifier data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

key_modifier

The value

to_string() [5/18]

std::string zakero::to_string ( const Yetani::KeyState &  key_state )

noexcept

The key_state will be converted into a std::string.

Returns

A string

Parameters

key_state

The value

to_string() [6/18]

std::string zakero::to_string ( const Yetani::Output &  output )

noexcept

The output data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

output

The value

to_string() [7/18]

std::string zakero::to_string ( const Yetani::PointerAxis &  axis )

noexcept

The axis will be converted into a std::string.

Returns

A string

Parameters

axis

The value

to_string() [8/18]

std::string zakero::to_string ( const Yetani::PointerAxisSource &  source )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

source

The value

to_string() [9/18]

std::string zakero::to_string ( const Yetani::PointerAxisType &  type )

noexcept

The type will be converted into a std::string.

Returns

A string

Parameters

type

The value

to_string() [10/18]

std::string zakero::to_string ( const Yetani::PointerButton &  button )

noexcept

The button will be converted into a std::string.

Returns

A string

Parameters

button

The value

to_string() [11/18]

std::string zakero::to_string ( const Yetani::PointerButtonState &  button_state )

noexcept

The button_state will be converted into a std::string.

Returns

A string

Parameters

button_state

The value

to_string() [12/18]

std::string zakero::to_string ( const Yetani::PointMm &  point )

noexcept

The point will be converted into a std::string.

Returns

A string

Parameters

point

The value

to_string() [13/18]

std::string zakero::to_string ( const Yetani::PointPercent &  point )

noexcept

The point will be converted into a std::string.

Returns

A string

Parameters

point

The value

to_string() [14/18]

std::string zakero::to_string ( const Yetani::PointPixel &  point )

noexcept

The point will be converted into a std::string.

Returns

A string

Parameters

point

The value

to_string() [15/18]

std::string zakero::to_string ( const Yetani::SizeMm &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size

The value

to_string() [16/18]

std::string zakero::to_string ( const Yetani::SizePercent &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size

The value

to_string() [17/18]

std::string zakero::to_string ( const Yetani::SizePixel &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size

The value

to_string() [18/18]

std::string zakero::to_string ( const Yetani::WindowMode &  window_mode )

noexcept

The window_mode value will be converted into a std::string.

Returns

A string

Parameters

window_mode

The value