glass-effects

name	glass-effects
description	Apple glass/translucency effect integration via NSVisualEffectView (macOS) and UIVisualEffectView (iOS)
version	1.0

Apple Glass Effect Integration

This skill covers how to use Apple's vibrancy/translucency glass effects from Crystal via the ObjC runtime bridge. Glass effects allow UI to blur and tint the content behind a window or behind another view, creating the frosted-glass appearance used throughout macOS and iOS.

macOS: NSVisualEffectView

NSVisualEffectView is the macOS class for glass/translucency effects. It blurs and tints content behind the view or behind the window.

Three Key Properties

Property	Selector	Type	Description
Material	setMaterial:	NSInteger	What the effect looks like (color/tint)
Blending Mode	setBlendingMode:	NSInteger	What gets blurred (window background or view behind)
State	setState:	NSInteger	When the effect is active

Material Constants

Value	Name	Appearance
0	NSVisualEffectMaterialAppearanceBased	Matches app appearance (deprecated)
1	NSVisualEffectMaterialLight	Light translucent (deprecated, use Titlebar)
2	NSVisualEffectMaterialDark	Dark translucent (deprecated, use HUDWindow)
3	NSVisualEffectMaterialTitlebar	Window title bar appearance
4	NSVisualEffectMaterialSelection	Selected content appearance
5	NSVisualEffectMaterialMenu	Menu background
6	NSVisualEffectMaterialPopover	Popover background
7	NSVisualEffectMaterialSidebar	Sidebar background
8	NSVisualEffectMaterialHeaderView	Header view background
9	NSVisualEffectMaterialSheet	Sheet background
10	NSVisualEffectMaterialWindowBackground	Standard window background
11	NSVisualEffectMaterialHUDWindow	HUD window (heads-up display)
12	NSVisualEffectMaterialFullScreenUI	Full screen UI background
13	NSVisualEffectMaterialToolTip	Tooltip background
14	NSVisualEffectMaterialContentBackground	Content area background
15	NSVisualEffectMaterialUnderWindowBackground	Under-window background
16	NSVisualEffectMaterialUnderPageBackground	Under-page background

Blending Mode Constants

Value	Name	Description
0	BehindWindow	Blurs content behind the window (desktop, other windows)
1	WithinWindow	Blurs content behind this view within the same window

State Constants

Value	Name	Description
0	FollowsWindowActiveState	Effect active only when window is key/main
1	Active	Effect always active, even when window is not focused
2	Inactive	Effect always inactive (appears opaque)

Crystal Example: macOS Glass Window

# Create the visual effect view filling the content area
content_view = LibObjC.objc_send(window, sel("contentView"))
content_frame = LibObjC.objc_get_frame(content_view)

visual_effect = LibObjC.objc_send_rect(
  alloc("NSVisualEffectView"), sel("initWithFrame:"), content_frame)

# Material: HUDWindow (dark translucent panel)
LibObjC.objc_send_long(visual_effect, sel("setMaterial:"), 11_i64)

# Blending: behind the window (blurs desktop and other windows)
LibObjC.objc_send_long(visual_effect, sel("setBlendingMode:"), 0_i64)

# State: always active (even when window loses focus)
LibObjC.objc_send_long(visual_effect, sel("setState:"), 1_i64)

# Fill entire content area on resize
# Width-sizable (2) | Height-sizable (16) = 18
LibObjC.objc_set_autoresize(visual_effect, 18_u64)

# Add as subview of the content view
LibObjC.objc_add_subview(content_view, visual_effect)

# Now add UI elements as children of the visual effect view
LibObjC.objc_add_subview(visual_effect, title_label)
LibObjC.objc_add_subview(visual_effect, button)

Sidebar Glass Pattern

A common pattern for apps with a sidebar:

# Sidebar with sidebar material
sidebar = LibObjC.objc_send_rect(
  alloc("NSVisualEffectView"), sel("initWithFrame:"),
  LibObjC::CGRect.new(x: 0.0, y: 0.0, width: 240.0, height: 600.0))
LibObjC.objc_send_long(sidebar, sel("setMaterial:"), 7_i64)  # Sidebar
LibObjC.objc_send_long(sidebar, sel("setBlendingMode:"), 0_i64)
LibObjC.objc_send_long(sidebar, sel("setState:"), 0_i64)  # Follow window state

---

iOS: UIVisualEffectView

UIVisualEffectView is the iOS equivalent. It takes a UIVisualEffect object (either UIBlurEffect or UIVibrancyEffect) rather than individual material/blending/state properties.

UIBlurEffect Styles

Value	Name	Appearance
0	UIBlurEffectStyleExtraLight	Extra light blur
1	UIBlurEffectStyleLight	Light blur
2	UIBlurEffectStyleDark	Dark blur
3	UIBlurEffectStyleRegular	Adapts to light/dark mode (iOS 10+)
4	UIBlurEffectStyleProminent	Adapts, more opaque than Regular (iOS 10+)
10	UIBlurEffectStyleSystemMaterial	System material (iOS 13+)
11	UIBlurEffectStyleSystemMaterialLight	System material, light
12	UIBlurEffectStyleSystemMaterialDark	System material, dark
13	UIBlurEffectStyleSystemThinMaterial	Thin system material
14	UIBlurEffectStyleSystemUltraThinMaterial	Ultra thin system material
15	UIBlurEffectStyleSystemThickMaterial	Thick system material
16	UIBlurEffectStyleSystemChromeMaterial	Chrome-style system material

Crystal Example: iOS Glass

# Create a blur effect
blur_cls = LibObjC.objc_getClass("UIBlurEffect")
blur_effect = LibObjC.objc_send_long(
  blur_cls.as(LibObjC::Id), sel("effectWithStyle:"), 3_i64)  # Regular

# Create the visual effect view with the blur
visual_effect = LibObjC.objc_send_id(
  alloc("UIVisualEffectView"), sel("initWithEffect:"), blur_effect)

# Set frame (or use Auto Layout)
LibObjC.objc_send_rect_void(visual_effect, sel("setFrame:"),
  LibObjC::CGRect.new(x: 0.0, y: 0.0, width: 375.0, height: 667.0))

# Add UI elements to the contentView of the visual effect view
content_view = LibObjC.objc_send(visual_effect, sel("contentView"))
LibObjC.objc_add_subview(content_view, label)

Vibrancy Effect (Text/Icons on Glass)

For text and icons that should vibrate (change opacity/blend) with the glass:

# First create the blur effect
blur_effect = LibObjC.objc_send_long(
  LibObjC.objc_getClass("UIBlurEffect").as(LibObjC::Id),
  sel("effectWithStyle:"), 3_i64)

# Create vibrancy effect referencing the blur
vibrancy_cls = LibObjC.objc_getClass("UIVibrancyEffect")
vibrancy_effect = LibObjC.objc_send_id(
  vibrancy_cls.as(LibObjC::Id),
  sel("effectForBlurEffect:"), blur_effect)

# Create a secondary visual effect view for vibrant content
vibrant_view = LibObjC.objc_send_id(
  alloc("UIVisualEffectView"), sel("initWithEffect:"), vibrancy_effect)

# Add vibrant content (labels, icons) to this view's contentView
vibrant_content = LibObjC.objc_send(vibrant_view, sel("contentView"))
LibObjC.objc_add_subview(vibrant_content, label)

# Add the vibrant view inside the blur view's contentView
blur_content = LibObjC.objc_send(blur_visual_effect_view, sel("contentView"))
LibObjC.objc_add_subview(blur_content, vibrant_view)

---

ARM64 Calling Convention Considerations

Glass effects involve selectors with multiple Float64 (CGFloat) arguments, which makes the ARM64 calling convention critical.

The Problem

On ARM64, objc_msgSend is a raw assembly trampoline. It does not know the types of arguments. The caller must set up registers correctly:

• Integer/pointer arguments: x0 (self), x1 (_cmd), x2-x7 (method args)
• Float/double arguments: d0-d7 (independent register bank)
• CGRect: Passed as HFA (Homogeneous Floating-point Aggregate) in d0-d3

If you cast objc_msgSend to a function pointer with fewer double parameters than the actual ObjC method expects, the higher d registers contain garbage from prior computations. This produces random colors, invisible views (alpha = 0.0 or NaN), or crashes.

The Solution

Every unique combination of (return type, parameter types) has a dedicated C wrapper function in objc_bridge.c. Key wrappers used for glass effects:

// Material, blending, state (all take NSInteger = long)
void* objc_send_long(void* self, SEL sel, long arg1);

// NSVisualEffectView initWithFrame: (CGRect = 4 doubles as HFA)
void* objc_send_rect(void* self, SEL sel, CGRect rect);

// Autoresize mask (NSUInteger = unsigned long)
void objc_set_autoresize(void* view, unsigned long mask);

// NSColor creation (4 doubles: r, g, b, a)
void* nscolor_rgba(double r, double g, double b, double a);
void* nscolor_white_alpha(double white, double alpha);

Rule

Never cast objc_msgSend directly in Crystal with a generic function pointer. Always go through the typed wrapper in objc_bridge.c. If a new ObjC method needs a combination of argument types not covered by existing wrappers, add a new wrapper function to the bridge.

Existing Typed Wrappers for Float/Double Arguments

Wrapper	Signature	Use case
objc_send_1d	(id, SEL, d0)	Single double arg (e.g., setAlphaValue:)
objc_send_2d_ret_id	(id, SEL, d0, d1) -> id	Two doubles returning object
objc_send_4d_ret_id	(id, SEL, d0, d1, d2, d3) -> id	Four doubles returning object (color creation)
objc_send_rect	(id, SEL, CGRect) -> id	CGRect HFA argument (frame init)
objc_send_rect_void	(id, SEL, CGRect)	CGRect HFA, no return (setFrame:)
nscolor_rgba	(r, g, b, a) -> id	NSColor RGBA creation
nscolor_srgba	(r, g, b, a) -> id	NSColor sRGB creation
nscolor_white_alpha	(w, a) -> id	NSColor grayscale creation

---

Integration with the UI Component System

When glass effects are integrated into the cross-platform UI::View system, they would be handled at the renderer level rather than as a view type. For example, the AppKit::Renderer could apply glass effects to any view with a specific background configuration:

# Future API concept
stack = UI::VStack.new(spacing: 12.0)
stack.background = UI::GlassBackground.new(
  material: :sidebar,
  blending: :behind_window
)

The web renderer would map this to CSS backdrop-filter: blur(), the AppKit renderer to NSVisualEffectView, and the UIKit renderer to UIVisualEffectView.

---

Working Demo Reference

A complete working macOS app with glass effects is at:

/Users/crimsonknight/open_source_coding_projects/crystal/samples/cross_platform/macos_app.cr

Build and run:

cd /Users/crimsonknight/open_source_coding_projects/crystal/samples/cross_platform
clang -c objc_bridge.c -o objc_bridge.o
bin/crystal build macos_app.cr --link-flags="objc_bridge.o" -o macos_app
./macos_app

This demo creates a window with NSVisualEffectMaterialHUDWindow (material 13), BehindWindow blending (0), and Active state (1), showing Crystal-generated labels and a button on top of the glass surface.