/**
 ** CuasRTLib.java
 **
 ** Copyright (C) 2026 Elphel, Inc.
 **
 ** -----------------------------------------------------------------------------**
 **
 **  CuasRTLib.java is free software: you can redistribute it and/or modify
 **  it under the terms of the GNU General Public License as published by
 **  the Free Software Foundation, either version 3 of the License, or
 **  (at your option) any later version.
 **
 **  This program is distributed in the hope that it will be useful,
 **  but WITHOUT ANY WARRANTY; without even the implied warranty of
 **  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 **  GNU General Public License for more details.
 **
 **  You should have received a copy of the GNU General Public License
 **  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ** -----------------------------------------------------------------------------**
 */
package com.elphel.imagej.cuas.rt;

/**
 * JNA binding to libcuasrt.so — the native CUDA real-time detector library.
 *
 * STATUS: stub — activate when JNA is added to pom.xml.
 *
 * -------------------------------------------------------------------------
 * TO ACTIVATE: add to pom.xml dependencies:
 *
 *   <dependency>
 *     <groupId>net.java.dev.jna</groupId>
 *     <artifactId>jna</artifactId>
 *     <version>5.14.0</version>
 *   </dependency>
 *
 * Then replace this class with the active interface (sketch below).
 * -------------------------------------------------------------------------
 *
 * ACTIVE INTERFACE SKETCH (not compiled — JNA not yet on classpath):
 *
 *   import com.sun.jna.Library;
 *   import com.sun.jna.Native;
 *   import com.sun.jna.Pointer;
 *   import com.sun.jna.Structure;
 *   import java.util.Arrays;
 *   import java.util.List;
 *
 *   // RtParamsJna: JNA Structure mapping to C RtParams in rt_lib.h
 *   public static class RtParamsJna extends Structure {
 *       public int   max_vel;
 *       public int   width;
 *       public int   height;
 *       public float mem_coeff;
 *       public float obs_coeff;
 *       public float leaky_slope;
 *       public float peak_thresh;
 *
 *       @Override protected List<String> getFieldOrder() {
 *           return Arrays.asList("max_vel","width","height",
 *                                "mem_coeff","obs_coeff","leaky_slope","peak_thresh");
 *       }
 *   }
 *
 *   public interface CuasRTLib extends Library {
 *       CuasRTLib INSTANCE = Native.load("cuasrt", CuasRTLib.class);
 *
 *       // Create GPU context; returns opaque handle.
 *       Pointer cuasrt_create(int width, int height, RtParamsJna p);
 *
 *       // Destroy GPU context and free all GPU memory.
 *       void    cuasrt_destroy(Pointer ctx);
 *
 *       // Layer 1 matched filter.
 *       // fpixels: [nframes * width * height], row-major, host memory.
 *       // layer1Out: [n_chan * width * height] output, n_chan = (2*max_vel+1)^2.
 *       void    cuasrt_layer1(Pointer ctx, float[] fpixels, int nframes, float[] layer1Out);
 *
 *       // Update accumulation buffer; returns number of peaks found.
 *       // layer1Out:  [n_chan * width * height] from cuasrt_layer1.
 *       // accumBuf:   [n_chan * width * height] persistent state (in/out).
 *       // peaksXy:    output [(x,y) pairs], length >= maxPeaks*2.
 *       int     cuasrt_update_accum(Pointer ctx,
 *                                   float[] layer1Out, float[] accumBuf,
 *                                   RtParamsJna p, float[] peaksXy, int maxPeaks);
 *   }
 *
 * -------------------------------------------------------------------------
 * LIBRARY PATH:
 *   Set -Djna.library.path=/path/to/cuas_rt_gpu/build at JVM startup,
 *   or place libcuasrt.so on LD_LIBRARY_PATH.
 *   libcudart.so must also be accessible (ships with CUDA toolkit).
 *
 * CUDA CONTEXT:
 *   libcuasrt.so creates its own CUDA context (device 0).
 *   It runs independently of the JCuda tile-processor context.
 *   When both pipelines run together, context sharing via cudaSetDevice
 *   (CUDA 12 primary context) can be added without API changes.
 * -------------------------------------------------------------------------
 */
public final class CuasRTLib {
    // Placeholder — replace with active JNA interface once JNA is in pom.xml.
    private CuasRTLib() {}
}
