% tinyrox says don't edit this manually, but it can't stop you!
\name{txt2img_sdxl}
\alias{txt2img_sdxl}
\title{Generate an image from a text prompt using SDXL}
\usage{
txt2img_sdxl(prompt, negative_prompt = NULL, img_dim = 1024, pipeline = NULL,
             devices = "auto", memory_profile = NULL, unet_dtype_str = NULL,
             download_models = FALSE, scheduler = "ddim", timesteps = NULL,
             initial_latents = NULL, num_inference_steps = 30,
             guidance_scale = 7.5, seed = NULL, save_file = TRUE,
             filename = NULL, metadata_path = NULL, use_native_decoder = FALSE,
             use_native_text_encoder = FALSE, use_native_unet = FALSE,
             diffusers_dir = NULL, verbose = TRUE, ...)
}
\arguments{
\item{prompt}{A character string prompt describing the image to generate.}

\item{negative_prompt}{Optional negative prompt to guide the generation.}

\item{img_dim}{Dimension of the output image (e.g., 512 for 512x512).}

\item{pipeline}{Optional A pre-loaded diffusion pipeline. If `NULL`, it will be loaded based on the model name and devices.}

\item{devices}{A named list of devices for each model component (e.g., `list(unet = "cuda", decoder = "cpu", text_encoder = "cpu")`),
or "auto" to use `auto_devices()`, or NULL to use memory_profile devices.}

\item{memory_profile}{Character or list. Memory profile for GPU-poor optimization:
"auto" for auto-detection, or a profile name ("full_gpu", "balanced", "unet_gpu", "cpu_only"),
or a list from `sdxl_memory_profile()`. When specified, overrides devices parameter.}

\item{unet_dtype_str}{Optional A character for dtype of the unet component (typically "float16" for cuda and "float32" for cpu; float32 is available for cuda).}

\item{download_models}{Logical indicating whether to download the model files if they are not found.}

\item{scheduler}{Scheduler to use (e.g., `"ddim"`, `"euler"`).}

\item{timesteps}{Optional A vector of timesteps to use.}

\item{initial_latents}{Optional initial latents for the diffusion process.}

\item{num_inference_steps}{Number of inference steps to run.}

\item{guidance_scale}{Scale for classifier-free guidance (typically 7.5).}

\item{seed}{Optional seed for reproducibility.}

\item{save_file}{Logical indicating whether to save the generated image.}

\item{filename}{Optional filename for saving the image. If `NULL`, a default name is generated.}

\item{metadata_path}{Optional file path to save metadata.}

\item{use_native_decoder}{Logical; if TRUE, uses native R torch decoder instead of TorchScript.
Native decoder has better GPU compatibility (especially Blackwell).}

\item{use_native_text_encoder}{Logical; if TRUE, uses native R torch text encoder instead of TorchScript.
Native text encoder has better GPU compatibility (especially Blackwell).}

\item{use_native_unet}{Logical; if TRUE, uses native R torch UNet instead of TorchScript.
Native UNet has better GPU compatibility (especially Blackwell).}

\item{diffusers_dir}{Optional path to a diffusers safetensors directory
(\code{unet/}, \code{vae/}, \code{text_encoder/}, \code{text_encoder_2/}).
When supplied, the pipeline is built end-to-end from safetensors via
\code{\link{sdxl_pipeline_from_safetensors}} (native, Blackwell-safe,
no TorchScript) and the other \code{use_native_*} flags are ignored.}

\item{verbose}{Logical. Print progress and memory status messages.}

\item{...}{Additional parameters passed to the diffusion process.}
}
\value{
An image array and metadata
}
\description{
Generate an image from a text prompt using SDXL
}
\examples{
\dontrun{
# Basic usage with auto-detection
img <- txt2img_sdxl("a cat wearing sunglasses in space")

# GPU-poor mode (8GB VRAM)
img <- txt2img_sdxl("a sunset over mountains", memory_profile = "unet_gpu")

# Explicit memory profile
profile <- sdxl_memory_profile(vram_gb = 8)
img <- txt2img_sdxl("a forest path", memory_profile = profile)
}
}
