/**
 * @file
 * Optional native handles and application-managed rendering.
 *
 * These extensions follow the core thread and lifetime rules. Handles are borrowed;
 * never destroy them or dispatch their native connection independently. Typed
 * backend accessors live in the yasl/native headers and are installed only for built
 * backends. Application-managed drawing currently supports Cocoa/Metal only.
 */
#ifndef YASL_NATIVE_H
#define YASL_NATIVE_H

#include "yasl/yasl.h"

#ifdef __cplusplus
extern "C" {
#endif

/* Optional platform interoperability. All handles are borrowed and expire on
 * object destruction. Check yasl_display_backend() before casting:
 *
 *              display                  surface
 * Wayland      struct wl_display *       struct wl_surface *
 * X11          Display *                 Window (cast through uintptr_t)
 * Cocoa        NSApplication *           NSWindow * (view: window.contentView)
 */
/**
 * Get a borrowed, backend-specific display handle.
 * @param d Display, or NULL.
 * @return Native handle, or NULL. Inspect yasl_display_backend() before casting.
 * Prefer a typed accessor from yasl/native/wayland.h, x11.h, or cocoa.h.
 * The handle expires on display close; do not close or dispatch it independently.
 */
YASL_API void *yasl_display_get_native_handle(struct yasl_display *d);
/**
 * Get a borrowed, backend-specific surface handle.
 * @param s Surface, or NULL.
 * @return Native handle, or NULL. X11 encodes a Window through uintptr_t.
 * Prefer typed accessors. The handle expires on surface destruction. Do not
 * change native ownership, event masks, buffer attachment, or surface roles.
 */
YASL_API void *yasl_surface_get_native_handle(struct yasl_surface *s);

/* Create a surface for application-managed native rendering. graphics_device
 * must be non-NULL; currently an id<MTLDevice> on Cocoa, retained by the surface.
 * Other backends return NULL with errno=ENOTSUP. CPU rendering uses the ordinary
 * yasl_surface_create_toplevel() and requires no native device. */
/**
 * Create a toplevel for application-managed native rendering.
 * @param d Display with YASL_CAP_NATIVE_GRAPHICS.
 * @param spec Copied toplevel options, with logical-pixel size.
 * @param graphics_device Required native graphics device; currently id<MTLDevice> on Cocoa.
 * @return Owned surface, or NULL with errno set: EINVAL for invalid arguments,
 * ENOTSUP for an unsupported backend, or a backend error.
 * Cocoa retains the device. Query the drawable during draw, submit/present it,
 * then call yasl_surface_present() to record submission.
 */
YASL_API struct yasl_surface *yasl_surface_create_native(struct yasl_display *d,
        const struct yasl_surface_spec *spec, void *graphics_device);

/** Borrowed native drawable for the current draw target, currently Cocoa/Metal. */
struct yasl_native_frame {
    /** Borrowed id<CAMetalDrawable> on Cocoa. */
    void *drawable;
    /** Cocoa CAMetalLayer presentsWithTransaction setting for this frame. */
    bool transaction;
};

/* Query the current draw target's native drawable. Returns false for unsupported
 * backends, stale targets, or outside the draw callback. The result expires on
 * successful present, callback return, or surface destruction. Native renderers
 * submit/present the drawable, then call yasl_surface_present() to record it. */
/**
 * Get the current draw target's native drawable.
 * @param s Surface currently being drawn.
 * @param target Exact framebuffer identity supplied to this draw callback.
 * @param out Required output native frame.
 * @return true if available, false for NULL arguments, unsupported backends,
 * stale targets, or calls outside draw. The drawable is borrowed and expires on
 * successful present, callback return, or surface destruction. Currently Cocoa only.
 */
YASL_API bool yasl_surface_get_native_frame(struct yasl_surface *s,
        const struct yasl_framebuffer *target, struct yasl_native_frame *out);

#ifdef __cplusplus
}
#endif

#endif /* YASL_NATIVE_H */