PolytreeDE/picom
1
0
Fork 0
mirror of https://github.com/yshui/picom.git synced 2025-10-30 23:46:46 -04:00
Code Releases Activity

plugin: add picom API headers

Browse source 
And add a pkgconfig file so they can be found.

Signed-off-by: Yuxuan Shui <yshuiv7@gmail.com>
This commit is contained in:
Yuxuan Shui 2024-05-23 14:30:55 +01:00
parent d9bc1798b1
commit f5bebb3e2e
No known key found for this signature in database
GPG key ID: D3A4405BE6CC17F4
36 changed files with 611 additions and 542 deletions
Download patch file Download diff file Expand all files Collapse all files

3
include/meson.build Normal file
View file

@ -0,0 +1,3 @@
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) Yuxuan Shui <yshuiv7@gmail.com>
subdirs('picom')

14
include/picom/api.h Normal file
View file

@ -0,0 +1,14 @@
// SPDX-License-Identifier: MPL-2.0
// Copyright (c) Yuxuan Shui <yshuiv7@gmail.com>
#pragma once
#include <stdint.h>
#define PICOM_API_MAJOR (0UL)
#define PICOM_API_MINOR (1UL)
struct picom_api {};
const struct picom_api *
picom_api_get_interfaces(uint64_t major, uint64_t minor, const char *context);

485
include/picom/backend.h Normal file
View file

@ -0,0 +1,485 @@
// SPDX-License-Identifier: MPL-2.0
// Copyright (c) Yuxuan Shui <yshuiv7@gmail.com>
#pragma once
#include <pixman-1/pixman.h>
#include <stdbool.h>
#include <xcb/xproto.h>
#include "types.h"
#define PICOM_BACKEND_MAJOR (1UL)
#define PICOM_BACKEND_MINOR (0UL)
#define PICOM_BACKEND_MAKE_VERSION(major, minor) ((major) * 1000 + (minor))
typedef pixman_region32_t region_t;
struct xvisual_info {
/// Bit depth of the red component
int red_size;
/// Bit depth of the green component
int green_size;
/// Bit depth of the blue component
int blue_size;
/// Bit depth of the alpha component
int alpha_size;
/// The depth of X visual
int visual_depth;
xcb_visualid_t visual;
};
typedef struct session session_t;
struct managed_win;
struct ev_loop;
struct backend_operations;
typedef struct backend_base {
struct backend_operations *ops;
struct x_connection *c;
struct ev_loop *loop;
/// Whether the backend can accept new render request at the moment
bool busy;
// ...
} backend_t;
// This mimics OpenGL's ARB_robustness extension, which enables detection of GPU context
// resets.
// See: https://www.khronos.org/registry/OpenGL/extensions/ARB/ARB_robustness.txt, section
// 2.6 "Graphics Reset Recovery".
enum device_status {
DEVICE_STATUS_NORMAL,
DEVICE_STATUS_RESETTING,
};
enum shader_attributes {
// Whether the shader needs to be render regardless of whether the window is
// updated.
SHADER_ATTRIBUTE_ANIMATED = 1,
};
struct gaussian_blur_args {
int size;
double deviation;
};
struct box_blur_args {
int size;
};
struct kernel_blur_args {
struct conv **kernels;
int kernel_count;
};
struct dual_kawase_blur_args {
int size;
int strength;
};
typedef struct image_handle {
// Intentionally left blank
} *image_handle;
/// A mask for various backend operations.
///
/// The mask is composed of both a mask region and a mask image. The resulting mask
/// is the intersection of the two. The mask image can be modified by the `corner_radius`
/// and `inverted` properties. Note these properties have no effect on the mask region.
struct backend_mask_image {
/// Mask image, can be NULL.
///
/// Mask image must be an image that was created with the
/// `BACKEND_IMAGE_FORMAT_MASK` format. Using an image with a wrong format as mask
/// is undefined behavior.
image_handle image;
/// Corner radius of the mask image, the corners of the mask image will be
/// rounded.
double corner_radius;
/// Origin of the mask image, in the source image's coordinate.
ivec2 origin;
/// Whether the mask image should be inverted.
bool inverted;
};
struct backend_blur_args {
/// The blur context
void *blur_context;
/// The source mask for the blur operation, may be NULL. Only parts of the source
/// image covered by the mask should participate in the blur operation.
const struct backend_mask_image *source_mask;
/// Region of the target image that will be covered by the blur operation, in the
/// source image's coordinate.
const region_t *target_mask;
/// Source image
image_handle source_image;
/// Opacity of the blurred image
double opacity;
};
struct backend_blit_args {
/// Source image, can be NULL.
image_handle source_image;
/// Mask for the source image. may be NULL. Only contents covered by the mask
/// should participate in the blit operation. This applies to the source image
/// before it's scaled.
const struct backend_mask_image *source_mask;
/// Mask for the target image. Only regions of the target image covered by this
/// mask should be modified. This is the target's coordinate system.
const region_t *target_mask;
/// Custom shader for this blit operation.
void *shader;
/// Opacity of the source image.
double opacity;
/// Dim level of the source image.
double dim;
/// Brightness limit of the source image. Source image
/// will be normalized so that the maximum brightness is
/// this value.
double max_brightness;
/// Scale factor for the horizontal and vertical direction (X for horizontal,
/// Y for vertical).
vec2 scale;
/// Corner radius of the source image BEFORE scaling. The corners of
/// the source image will be rounded.
double corner_radius;
/// Effective size of the source image BEFORE scaling, set where the corners
/// of the image are.
ivec2 effective_size;
/// Border width of the source image BEFORE scaling. This is used with
/// `corner_radius` to create a border for the rounded corners.
/// Setting this has no effect if `corner_radius` is 0.
int border_width;
/// Whether the source image should be inverted.
bool color_inverted;
};
enum backend_image_format {
/// A format that can be used for normal rendering, and binding
/// X pixmaps.
/// Images created with `bind_pixmap` have this format automatically.
BACKEND_IMAGE_FORMAT_PIXMAP,
/// Like `BACKEND_IMAGE_FORMAT_PIXMAP`, but the image has a higher
/// precision. Support is optional.
BACKEND_IMAGE_FORMAT_PIXMAP_HIGH,
/// A format that can be used for masks.
BACKEND_IMAGE_FORMAT_MASK,
};
enum backend_image_capability {
/// Image can be sampled from. This is required for `blit` and `blur` source
/// images. All images except the back buffer should have this capability.
/// Note that `copy_area` should work without this capability, this is so that
/// blurring the back buffer could be done.
BACKEND_IMAGE_CAP_SRC = 1 << 0,
/// Image can be rendered to. This is required for target images of any operation.
/// All images except bound X pixmaps should have this capability.
BACKEND_IMAGE_CAP_DST = 1 << 1,
};
enum backend_command_op {
BACKEND_COMMAND_INVALID = -1,
BACKEND_COMMAND_BLIT,
BACKEND_COMMAND_BLUR,
BACKEND_COMMAND_COPY_AREA,
};
/// Symbolic references used as render command source images. The actual `image_handle`
/// will later be filled in by the renderer using this symbolic reference.
enum backend_command_source {
BACKEND_COMMAND_SOURCE_WINDOW,
BACKEND_COMMAND_SOURCE_SHADOW,
BACKEND_COMMAND_SOURCE_BACKGROUND,
};
// TODO(yshui) might need better names
struct backend_command {
enum backend_command_op op;
ivec2 origin;
enum backend_command_source source;
union {
struct {
struct backend_blit_args blit;
/// Region of the screen that will be covered by this blit
/// operations, in screen coordinates.
region_t opaque_region;
};
struct {
image_handle source_image;
const region_t *region;
} copy_area;
struct backend_blur_args blur;
};
/// Source mask for the operation.
/// If the `source_mask` of the operation's argument points to this, a mask image
/// will be created for the operation for the renderer.
struct backend_mask_image source_mask;
/// Target mask for the operation.
region_t target_mask;
};
enum backend_quirk {
/// Backend cannot do blur quickly. The compositor will avoid using blur to create
/// shadows on this backend
BACKEND_QUIRK_SLOW_BLUR = 1 << 0,
};
struct backend_operations {
// =========== Initialization ===========
/// Initialize the backend, prepare for rendering to the target window.
backend_t *(*init)(session_t *, xcb_window_t) __attribute__((nonnull(1)));
void (*deinit)(backend_t *backend_data) __attribute__((nonnull(1)));
/// Called when rendering will be stopped for an unknown amount of
/// time (e.g. when screen is unredirected). Free some resources.
///
/// Optional, not yet used
void (*pause)(backend_t *backend_data, session_t *ps);
/// Called before rendering is resumed
///
/// Optional, not yet used
void (*resume)(backend_t *backend_data, session_t *ps);
/// Called when root window size changed. All existing image data ever
/// returned by this backend should remain valid after this call
/// returns.
///
/// Optional
void (*root_change)(backend_t *backend_data, session_t *ps);
// =========== Rendering ============
/// Called before when a new frame starts.
///
/// Optional
void (*prepare)(backend_t *backend_data, const region_t *reg_damage);
/// Multiply the alpha channel of the target image by a given value.
///
/// @param backend_data backend data
/// @param target an image handle, cannot be NULL.
/// @param alpha the alpha value to multiply
/// @param region the region to apply the alpha, in the target image's
/// coordinate.
bool (*apply_alpha)(struct backend_base *backend_data, image_handle target,
double alpha, const region_t *region)
__attribute__((nonnull(1, 2, 4)));
/// Copy pixels from a source image on to the target image.
///
/// Some effects may be applied. If the region specified by the mask
/// contains parts that are outside the source image, the source image
/// will be repeated to fit.
///
/// Source and target MUST NOT be the same image.
///
/// @param backend_data backend data
/// @param origin the origin of the operation, in the target image's
/// coordinate.
/// @param target an image handle, cannot be NULL.
/// @param args arguments for blit
/// @return whether the operation is successful
bool (*blit)(struct backend_base *backend_data, ivec2 origin, image_handle target,
const struct backend_blit_args *args) __attribute__((nonnull(1, 3, 4)));
/// Blur a given region of a source image and store the result in the
/// target image.
///
/// The blur operation might access pixels outside the mask region, the
/// amount of pixels accessed can be queried with `get_blur_size`. If
/// pixels outside the source image are accessed, the result will be
/// clamped to the edge of the source image.
///
/// Source and target may be the same image.
///
/// @param backend_data backend data
/// @param origin the origin of the operation, in the target image's
/// coordinate.
/// @param target an image handle, cannot be NULL.
/// @param args argument for blur
/// @return whether the operation is successful
bool (*blur)(struct backend_base *backend_data, ivec2 origin, image_handle target,
const struct backend_blur_args *args) __attribute__((nonnull(1, 3, 4)));
/// Direct copy of pixels from a source image on to the target image.
/// This is a simpler version of `blit`, without any effects. Note unlike `blit`,
/// if `region` tries to sample from outside the source image, instead of
/// repeating, the result will be clamped to the edge of the source image.
/// Blending should not be applied for the copy.
///
/// Source and target MUST NOT be the same image.
///
/// @param backend_data backend data
/// @param origin the origin of the operation, in the target image's
/// coordinate.
/// @param target an image handle, cannot be NULL.
/// @param source an image handle, cannot be NULL.
/// @param region the region to copy, in the target image's coordinate.
/// @return whether the operation is successful
bool (*copy_area)(struct backend_base *backend_data, ivec2 origin,
image_handle target, image_handle source, const region_t *region)
__attribute__((nonnull(1, 3, 4, 5)));
/// Similar to `copy_area`, but is specialized for copying from a higher
/// precision format to a lower precision format. It has 2 major differences from
/// `copy_area`:
///
/// 1. This function _may_ use dithering when copying from a higher precision
/// format to a lower precision format. But this is not required.
/// 2. This function only needs to support copying from an image with the SRC
/// capability. Unlike `copy_area`, which supports copying from any image.
///
/// It's perfectly legal to have this pointing to the same function as
/// `copy_area`, if the backend doesn't support dithering.
///
/// @param backend_data backend data
/// @param origin the origin of the operation, in the target image's
/// coordinate.
/// @param target an image handle, cannot be NULL.
/// @param source an image handle, cannot be NULL.
/// @param region the region to copy, in the target image's coordinate.
/// @return whether the operation is successful
bool (*copy_area_quantize)(struct backend_base *backend_data, ivec2 origin,
image_handle target, image_handle source,
const region_t *region)
__attribute__((nonnull(1, 3, 4, 5)));
/// Initialize an image with a given color value. If the image has a mask format,
/// only the alpha channel of the color is used.
///
/// @param backend_data backend data
/// @param target an image handle, cannot be NULL.
/// @param color the color to fill the image with
/// @return whether the operation is successful
bool (*clear)(struct backend_base *backend_data, image_handle target,
struct color color) __attribute__((nonnull(1, 2)));
/// Present the back buffer to the target window. Ideally the backend should keep
/// track of the region of the back buffer that has been updated, and use relevant
/// mechanism (when possible) to present only the updated region.
bool (*present)(struct backend_base *backend_data) __attribute__((nonnull(1)));
// ============ Resource management ===========
/// Create a shader object from a shader source.
///
/// Optional
void *(*create_shader)(backend_t *backend_data, const char *source)
__attribute__((nonnull(1, 2)));
/// Free a shader object.
///
/// Required if create_shader is present.
void (*destroy_shader)(backend_t *backend_data, void *shader)
__attribute__((nonnull(1, 2)));
/// Create a new, uninitialized image with the given format and size.
///
/// @param backend_data backend data
/// @param format the format of the image
/// @param size the size of the image
image_handle (*new_image)(struct backend_base *backend_data,
enum backend_image_format format, ivec2 size)
__attribute__((nonnull(1)));
/// Bind a X pixmap to the backend's internal image data structure.
///
/// @param backend_data backend data
/// @param pixmap X pixmap to bind
/// @param fmt information of the pixmap's visual
/// @return backend specific image handle for the pixmap. May be
/// NULL.
image_handle (*bind_pixmap)(struct backend_base *backend_data, xcb_pixmap_t pixmap,
struct xvisual_info fmt) __attribute__((nonnull(1)));
/// Acquire the image handle of the back buffer.
///
/// @param backend_data backend data
image_handle (*back_buffer)(struct backend_base *backend_data);
/// Free resources associated with an image data structure. Releasing the image
/// returned by `back_buffer` should be a no-op.
///
/// @param image the image to be released, cannot be NULL.
/// @return if this image is created by `bind_pixmap`, the X pixmap; 0
/// otherwise.
xcb_pixmap_t (*release_image)(struct backend_base *backend_data, image_handle image)
__attribute__((nonnull(1, 2)));
// =========== Query ===========
/// Get backend quirks
/// @return a bitmask of `enum backend_quirk`.
uint32_t (*quirks)(struct backend_base *backend_data) __attribute__((nonnull(1)));
/// Check if an optional image format is supported by the backend.
bool (*is_format_supported)(struct backend_base *backend_data,
enum backend_image_format format)
__attribute__((nonnull(1)));
/// Return the capabilities of an image.
uint32_t (*image_capabilities)(struct backend_base *backend_data, image_handle image)
__attribute__((nonnull(1, 2)));
/// Get the attributes of a shader.
///
/// Optional, Returns a bitmask of attributes, see `shader_attributes`.
uint64_t (*get_shader_attributes)(backend_t *backend_data, void *shader)
__attribute__((nonnull(1, 2)));
/// Get the age of the buffer content we are currently rendering on top
/// of. The buffer that has just been `present`ed has a buffer age of 1.
/// Every time `present` is called, buffers get older. Return -1 if the
/// buffer is empty.
///
/// Optional
int (*buffer_age)(backend_t *backend_data);
/// Get the render time of the last frame. If the render is still in progress,
/// returns false. The time is returned in `ts`. Frames are delimited by the
/// present() calls. i.e. after a present() call, last_render_time() should start
/// reporting the time of the just presented frame.
///
/// Optional, if not available, the most conservative estimation will be used.
bool (*last_render_time)(backend_t *backend_data, struct timespec *ts);
/// The maximum number buffer_age might return.
int max_buffer_age;
// =========== Post-processing ============
/// Create a blur context that can be used to call `blur` for images with a
/// specific format.
void *(*create_blur_context)(backend_t *base, enum blur_method,
enum backend_image_format format, void *args);
/// Destroy a blur context
void (*destroy_blur_context)(backend_t *base, void *ctx);
/// Get how many pixels outside of the blur area is needed for blur
void (*get_blur_size)(void *blur_context, int *width, int *height);
// =========== Misc ============
/// Return the driver that is been used by the backend
enum driver (*detect_driver)(backend_t *backend_data);
void (*diagnostics)(backend_t *backend_data);
enum device_status (*device_status)(backend_t *backend_data);
};
/// Register a new backend, `major` and `minor` should be the version of the picom backend
/// interface. You should just pass `PICOM_BACKEND_MAJOR` and `PICOM_BACKEND_MINOR` here.
/// `name` is the name of the backend, `init` is the function to initialize the backend,
/// `can_present` should be true if the backend can present the back buffer to the screen,
/// false otherwise (e.g. if the backend does off screen rendering, etc.)
bool backend_register(uint64_t major, uint64_t minor, const char *name,
struct backend_base *(*init)(session_t *ps, xcb_window_t target),
bool can_present);
/// Define a backend entry point. (Note constructor priority 202 is used here because 1xx
/// is reversed by test.h, and 201 is used for logging initialization.)
#define BACKEND_ENTRYPOINT(func) static void __attribute__((constructor(202))) func(void)

8
include/picom/meson.build Normal file
View file

@ -0,0 +1,8 @@
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) Yuxuan Shui <yshuiv7@gmail.com>
api_headers = [
'api.h'
'backend.h'
]
install_headers(api_headers, subdir: 'picom')

179
include/picom/types.h Normal file
View file

@ -0,0 +1,179 @@
// SPDX-License-Identifier: MPL-2.0
// Copyright (c) Yuxuan Shui <yshuiv7@gmail.com>
#pragma once
/// Some common types
#include <limits.h>
#include <math.h>
#include <stdbool.h>
#include <stdint.h>
enum blur_method {
BLUR_METHOD_NONE = 0,
BLUR_METHOD_KERNEL,
BLUR_METHOD_BOX,
BLUR_METHOD_GAUSSIAN,
BLUR_METHOD_DUAL_KAWASE,
BLUR_METHOD_INVALID,
};
/// Enumeration type to represent switches.
typedef enum {
OFF = 0, // false
ON, // true
UNSET
} switch_t;
enum tristate { TRI_FALSE = -1, TRI_UNKNOWN = 0, TRI_TRUE = 1 };
/// A structure representing margins around a rectangle.
typedef struct {
int top;
int left;
int bottom;
int right;
} margin_t;
struct color {
double red, green, blue, alpha;
};
typedef uint32_t opacity_t;
typedef struct vec2 {
union {
double x;
double width;
};
union {
double y;
double height;
};
} vec2;
typedef struct ivec2 {
union {
int x;
int width;
};
union {
int y;
int height;
};
} ivec2;
struct ibox {
ivec2 origin;
ivec2 size;
};
static const vec2 SCALE_IDENTITY = {1.0, 1.0};
static inline vec2 ivec2_as(ivec2 a) {
return (vec2){
.x = a.x,
.y = a.y,
};
}
static inline ivec2 ivec2_add(ivec2 a, ivec2 b) {
return (ivec2){
.x = a.x + b.x,
.y = a.y + b.y,
};
}
static inline ivec2 ivec2_sub(ivec2 a, ivec2 b) {
return (ivec2){
.x = a.x - b.x,
.y = a.y - b.y,
};
}
static inline bool ivec2_eq(ivec2 a, ivec2 b) {
return a.x == b.x && a.y == b.y;
}
static inline ivec2 ivec2_neg(ivec2 a) {
return (ivec2){
.x = -a.x,
.y = -a.y,
};
}
/// Saturating cast from a vec2 to a ivec2
static inline ivec2 vec2_as(vec2 a) {
return (ivec2){
.x = (int)fmin(fmax(a.x, INT_MIN), INT_MAX),
.y = (int)fmin(fmax(a.y, INT_MIN), INT_MAX),
};
}
static inline vec2 vec2_add(vec2 a, vec2 b) {
return (vec2){
.x = a.x + b.x,
.y = a.y + b.y,
};
}
static inline vec2 vec2_ceil(vec2 a) {
return (vec2){
.x = ceil(a.x),
.y = ceil(a.y),
};
}
static inline vec2 vec2_floor(vec2 a) {
return (vec2){
.x = floor(a.x),
.y = floor(a.y),
};
}
static inline bool vec2_eq(vec2 a, vec2 b) {
return a.x == b.x && a.y == b.y;
}
static inline vec2 vec2_scale(vec2 a, vec2 scale) {
return (vec2){
.x = a.x * scale.x,
.y = a.y * scale.y,
};
}
/// Check if two boxes have a non-zero intersection area.
static inline bool ibox_overlap(struct ibox a, struct ibox b) {
if (a.size.width <= 0 || a.size.height <= 0 || b.size.width <= 0 || b.size.height <= 0) {
return false;
}
if (a.origin.x <= INT_MAX - a.size.width && a.origin.y <= INT_MAX - a.size.height &&
(a.origin.x + a.size.width <= b.origin.x ||
a.origin.y + a.size.height <= b.origin.y)) {
return false;
}
if (b.origin.x <= INT_MAX - b.size.width && b.origin.y <= INT_MAX - b.size.height &&
(b.origin.x + b.size.width <= a.origin.x ||
b.origin.y + b.size.height <= a.origin.y)) {
return false;
}
return true;
}
static inline bool ibox_eq(struct ibox a, struct ibox b) {
return ivec2_eq(a.origin, b.origin) && ivec2_eq(a.size, b.size);
}
static inline ivec2 ivec2_scale_ceil(ivec2 a, vec2 scale) {
vec2 scaled = vec2_scale(ivec2_as(a), scale);
return vec2_as(vec2_ceil(scaled));
}
static inline ivec2 ivec2_scale_floor(ivec2 a, vec2 scale) {
vec2 scaled = vec2_scale(ivec2_as(a), scale);
return vec2_as(vec2_floor(scaled));
}
#define MARGIN_INIT \
{ 0, 0, 0, 0 }