inntroduce better defaults for common cases (#71)

Co-authored-by: sandwich <dskvr@users.noreply.github.com>

Author: dskvr

docs/configuration/examples/basic.toml

@@ -5,7 +5,7 @@
 fps = 60                # Lower FPS for battery saving
 debug = false
 duration = 1.0          # 1 second workspace animation
-shift = 150             # Moderate parallax shift
+shift = 100             # Optimized parallax shift for 10 workspaces
 vsync = true
 easing = "expo"
 
@@ -20,11 +20,13 @@ easing = "expo"
 [[global.layers]]
 path = "~/Pictures/background.jpg"
 shift_multiplier = 0.5    # Moves at half speed
+scale = 1.2                # 20% larger to prevent edge smearing
 opacity = 1.0
 blur = 1.0                 # Slight blur for depth
 
 [[global.layers]]
 path = "~/Pictures/foreground.png"
-shift_multiplier = 1.0    # Normal parallax speed
+shift_multiplier = 0.75   # Reduced to stay within bounds
+scale = 1.2                # 20% larger to prevent edge smearing
 opacity = 0.95             # Slightly transparent
 blur = 0.0                 # Sharp foreground

docs/configuration/examples/multi-layer.toml

@@ -5,7 +5,7 @@
 fps = 144
 debug = false
 duration = 1.2
-shift = 250
+shift = 100  # Optimized for 10 workspaces without smearing
 vsync = true
 easing = "expo"
 
@@ -61,7 +61,7 @@ scale = 1.1
 # Layer 5: Foreground elements
 [[global.layers]]
 path = "~/walls/layer5_foreground.png"
-shift_multiplier = 1.2    # Faster than normal
+shift_multiplier = 1.0    # Full speed (but within bounds)
 opacity = 1.0
 blur = 0.0                # Sharp foreground
 fit = "contain"
@@ -70,7 +70,7 @@ align = { x = 0.5, y = 1.0 }  # Bottom-aligned
 # Layer 6: Overlay effects (optional)
 # [[global.layers]]
 # path = "~/walls/layer6_particles.png"
-# shift_multiplier = { x = 1.5, y = 0.5 }  # Different X/Y speeds
+# shift_multiplier = { x = 1.0, y = 0.5 }  # Different X/Y speeds
 # opacity = 0.3
 # blur = 0.0
 # fit = "cover"

examples/hyprlax.toml

@@ -1,9 +1,15 @@
 # Example hyprlax TOML configuration (scaffold)
+#
+# Default values optimized for 10 workspaces without edge smearing:
+# - shift = 100px per workspace (total 900px movement across 10 workspaces)
+# - layer scale = 1.2x (20% larger than viewport)
+# - For 1920px screen: 1.2x = 2304px, giving 192px margin each side
+# - This prevents edge artifacts while maintaining smooth parallax
 
 [global]
 fps = 144
 duration = 1.0
-shift = 200
+shift = 100  # Reduced from 200 to prevent smearing with typical 10 workspaces
 easing = "expo"
 debug = false
 vsync = false
@@ -12,12 +18,14 @@ idle_poll_rate = 2.0
 [[global.layers]]
 path = "images/bg.png"
 shift_multiplier = 0.25
+scale = 1.2  # 20% larger to accommodate parallax shift without edge artifacts
 opacity = 1.0
 blur = 0.0
 
 [[global.layers]]
 path = "images/fg.png"
-shift_multiplier = 1.0
+shift_multiplier = 0.75  # Reduced from 1.0 to stay within scaled bounds
+scale = 1.2  # Match background scale for consistency
 opacity = 0.9
 blur = 0.0
 

src/core/config.c

@@ -20,8 +20,8 @@ void config_set_defaults(config_t *cfg) {
 
     cfg->target_fps = 60;
     cfg->max_fps = 144;
-    cfg->shift_pixels = 150.0f;
-    cfg->scale_factor = 1.5f;
+    cfg->shift_pixels = 100.0f;  /* Reduced from 150 to prevent smearing with 10 workspaces */
+    cfg->scale_factor = 1.2f;    /* Reduced from 1.5 to match new shift defaults */
     cfg->animation_duration = 1.0;
     cfg->default_easing = EASE_CUBIC_OUT;
     cfg->vsync = false;  /* Default off to prevent GPU blocking when idle */

src/core/layer.c

@@ -48,7 +48,7 @@ parallax_layer_t* layer_create(const char *image_path, float shift_multiplier, f
 
     /* Content scaling defaults */
     layer->fit_mode = LAYER_FIT_STRETCH;
-    layer->content_scale = 1.0f;
+    layer->content_scale = 1.2f;  /* 20% larger to prevent edge smearing with 10 workspaces */
     layer->align_x = 0.5f;
     layer->align_y = 0.5f;
     layer->base_uv_x = 0.0f;

src/core/monitor.c

@@ -295,7 +295,7 @@ void monitor_handle_workspace_context_change(hyprlax_context_t *ctx,
         /* Calculate 2D offset for 2D models */
         offset_2d = workspace_calculate_offset_2d(&monitor->current_context,
                                                  new_context,
-                                                 monitor->config ? monitor->config->shift_pixels : 200.0f,
+                                                 monitor->config ? monitor->config->shift_pixels : 100.0f,
                                                  NULL);
         if (ctx && ctx->config.debug) {
             fprintf(stderr, "[DEBUG]   Using 2D offset calculation\n");
@@ -304,7 +304,7 @@ void monitor_handle_workspace_context_change(hyprlax_context_t *ctx,
         /* Calculate 1D offset for linear models */
         offset_1d = workspace_calculate_offset(&monitor->current_context,
                                               new_context,
-                                              monitor->config ? monitor->config->shift_pixels : 200.0f,
+                                              monitor->config ? monitor->config->shift_pixels : 100.0f,
                                               NULL);
         offset_2d.x = offset_1d;
         offset_2d.y = 0.0f;
@@ -349,7 +349,7 @@ void monitor_handle_workspace_context_change(hyprlax_context_t *ctx,
             int from_ws = old_context.data.workspace_id;
             int to_ws = new_context->data.workspace_id;
             int delta_ws = to_ws - from_ws;
-            float step = (monitor->config ? monitor->config->shift_pixels : 200.0f);
+            float step = (monitor->config ? monitor->config->shift_pixels : 100.0f);
             float base_x = monitor->animating ? monitor->animation_target_x : monitor->parallax_offset_x;
             absolute_target_x = base_x + delta_ws * step;
             absolute_target_y = 0.0f;

src/hyprlax.c

@@ -81,10 +81,10 @@ struct config {
     int max_workspaces;    // Maximum number of workspaces (detected from Hyprland)
     char *config_file_path;  // Path to the config file for resolving relative paths
 } config = {
-    .shift_per_workspace = 200.0f,  // More dramatic shift between workspaces
+    .shift_per_workspace = 100.0f,  // Optimized shift to prevent smearing with 10 workspaces
     .animation_duration = 1.0f,  // Longer duration - user can "feel" it settling
     .animation_delay = 0.0f,
-    .scale_factor = 1.5f,  // Increased scale to accommodate larger shifts
+    .scale_factor = 1.2f,  // 20% larger to accommodate parallax without edge artifacts
     .easing = EASE_EXPO_OUT,  // Exponential ease out - fast then very gentle settling
     .target_fps = 144,
     .vsync = 1,
@@ -1199,7 +1199,7 @@ void print_usage(const char *prog) {
     printf("   or: %s [OPTIONS] --layer <image:shift:opacity> [...]\n", prog);
     printf("   or: %s [OPTIONS] --config <config_file>\n\n", prog);
     printf("Options:\n");
-    printf("  -s, --shift <pixels>     Pixels to shift per workspace (default: 200)\n");
+    printf("  -s, --shift <pixels>     Pixels to shift per workspace (default: 100)\n");
     printf("  -d, --duration <seconds> Animation duration (default: 1.0)\n");
     printf("  --delay <seconds>        Delay before animation starts (default: 0)\n");
     printf("  -e, --easing <type>      Easing function (default: expo)\n");

src/hyprlax_main.c

@@ -419,7 +419,7 @@ static int parse_arguments(hyprlax_context_t *ctx, int argc, char **argv) {
                 printf("  -h, --help                Show this help message\n");
                 printf("  -v, --version             Show version information\n");
                 printf("  -f, --fps <rate>          Target FPS (default: 60)\n");
-                printf("  -s, --shift <pixels>      Shift amount per workspace (default: 150)\n");
+                printf("  -s, --shift <pixels>      Shift amount per workspace (default: 100)\n");
                 printf("  -d, --duration <seconds>  Animation duration (default: 1.0)\n");
                 printf("  -e, --easing <type>       Easing function (default: cubic)\n");
                 printf("  -c, --config <file>       Load configuration from file\n");

src/ipc.c

@@ -1369,7 +1369,7 @@ int ipc_handle_request(ipc_context_t* ctx, const char* request, char* response,
         hyprlax_context_t *app = (hyprlax_context_t*)ctx->app_context;
         if (!app) {
             if (strcmp(property, "fps") == 0) { snprintf(response, response_size, "60"); return 0; }
-            if (strcmp(property, "shift") == 0) { snprintf(response, response_size, "200"); return 0; }
+            if (strcmp(property, "shift") == 0) { snprintf(response, response_size, "100"); return 0; }
             if (strcmp(property, "duration") == 0) { snprintf(response, response_size, "1.000"); return 0; }
             if (strcmp(property, "easing") == 0) { snprintf(response, response_size, "cubic"); return 0; }
             if (ipc_error_codes_enabled()) snprintf(response, response_size, "Error(1217): Unknown property '%s'", property); else snprintf(response, response_size, "Error: Unknown property '%s'", property); return -1;

src/main.c

@@ -82,7 +82,7 @@ int main(int argc, char **argv) {
             printf("  -h, --help                Show this help message\n");
             printf("  -v, --version             Show version information\n");
             printf("  -f, --fps <rate>          Target FPS (default: 60)\n");
-            printf("  -s, --shift <pixels>      Shift amount per workspace (default: 150)\n");
+            printf("  -s, --shift <pixels>      Shift amount per workspace (default: 100)\n");
             printf("  -d, --duration <seconds>  Animation duration (default: 1.0)\n");
             printf("  -e, --easing <type>       Easing function (default: cubic)\n");
             printf("  -c, --config <file>       Load configuration from file\n");