#ifndef rdo_sampling_H
#define rdo_sampling_H
/* Tools to select the sampling sites. */

#define rdo_sampling_H_COPYRIGHT "Copyright © 2008 Danillo Pereira and J. Stolfi, UNICAMP"
/* Last edited on 2024-12-21 11:51:41 by stolfi */

#include <stdio.h>

#include <i2.h>
#include <argparser.h>
#include <dspmat.h>

#include <rdo_geometry.h>
#include <rdo_solid.h>
#include <rdo_finish.h>
#include <rdo_radiosity.h>
#include <rdo_camera.h>
#include <rdo_site.h>
#include <rdo_scene.h>

typedef struct sampling_options_t
  { /* !!! deveria ter opção para geração uniforme por rdo_solid. !!! */ 
    /* !!! deveria ter opção para borrifar na/da caixa envoltória da cena. !!! */ 
    /* !!! deveria ter opção para borrifar a partir de uma fonte dada. !!! */ 
    int maxNumSites;              /* Max number of sampling sites. */
    double minDist;               /* Min distance between sampling sites. */
    int numInitialSites;          /* Number of initial sampling sites. */
    bool_t sampleFromObserver;    /* Cast some initial rays from the camera's eye. */
    bool_t sampleFromAllSides;    /* Cast some rays from various sources outside the scene. */
    bool_t sampleFromLights;      /* Cast some rays from the light sources. */
    int secondarySamples_numGens; /* Number of secondary ray casting passes. */
    int secondarySamples_numRays; /* Number of secondary rays to cast from each primary ray. */
  } sampling_options_t;
  /* Additional parameters that control the site sampling process. */
        
site_vec_t rdo_sampling_choose_approx_basis_centers
  ( solid_vec_t *sds,
    dist_type_t tpDist,
    sampling_options_t *opSmp, 
    point3_t *eye 
  );
  /* Select the centroids of the basis sites for the solids {sds} and camera
     position {eye}, according to the options {tpDist} and {opSmp}. */

void rdo_sampling_generate_sites_by_projection
  ( solid_vec_t *sds, 
    point3_t corner[],
    point3_t *eye, 
    int n,
    site_vec_t *sts
  );
  /* Appends to the site list {*sts} a set of {n} new sites, obtained
    by casting {n} rays from the given {eye} point. The rays pass
    through random points on the surface of the axis-aligned box
    defined by opposite corners {corner[0],corner[1]}.
    Expands the list {} as needed. */

void rdo_sampling_generate_secondary_sites(solid_vec_t *sds, site_vec_t *sts, int num_rays);
  /* Appends to the site list {*sts} a set of new sites, obtained
    by casting {num_rays} random rays from each site already in the list.
    Considers only rays that hit some object at finite distance. 
    Expands the list {*sts} as needed. */

site_t rdo_sampling_generate_secondary_site(solid_vec_t *sds, site_t *sO);
  /* Generates a site that is presumably relevant for 
    computing the radiosity at site {*sO}.  To that end, casts a ray from {*sO}
    along a random direction, away from its tangent plane, and 
    returns the site where that ray first hits some solid object in the scene.
    If the ray fials to hit any solid object, returns a site with {.isd = -1}.
    Faisl if the point {sO->position} is inside some solid object. */

/* COMMAND LINE OPTIONS */

sampling_options_t *rdo_sampling_options_parse(argparser_t *pp);
  /* Parses the sampling options from the command line
    according to the syntax described in {sampling_options_HELP} 
    and {sampling_options_INFO}. */
  
#define sampling_options_HELP \
  "    -maxNumSites {NS_MAX} \\\n" \
  "    -minDist {DS_MIN} \\\n" \
  "    [ -numInitialSites {NS_INI} \\\n" \
  "    [ -sampleFromObserver ] \\\n" \
  "    [ -sampleFromAllSides ] \\\n" \
  "    [ -sampleFromLights ] \\\n" \
  "    [ -secondarySamples {N_GENS} {N_RAYS} ]"
  
#define sampling_options_INFO \
  "  -maxNumSites {NS_MAX}\n" \
  "    This mandatory parameter specifies the maximum number of sampling" \
  " sites (which are also the centroids of the approximation" \
  " basis elements) to use..\n" \
  "\n" \
  "  -minDist {DS_MIN}\n" \
  "    This mandatory parameter specifies the minimum distance" \
  " between sampling sites.\n" \
  "\n" \
  "  -numInitialSites {NS_INI}\n" \
  "    This optional parameter specifies the number of sampling" \
  " sites to generate initially, by casting rays from point(s)" \
  " outside the scene.  If it is not given, the program assumes" \
  " {NS_INI == NS_MAX}\n" \
  "\n" \
  "  -sampleFromObserver\n" \
  "    This flag, if given, specifies that the origin of each" \
  " initial sampling ray may be the camera's position.   If none" \
  " of of the flags \"-sampleFromObserver\"," \
  " \"-sampleFromAllSides\" or \"-sampleFromLights\" is given," \
  " assumes all three are given.\n" \
  "\n" \
  "  -sampleFromAllSides\n" \
  "    This flag, if given, specifies that the origin of each" \
  " initial sampling ray may be a random point outside the scene.  If none" \
  " of the flags \"-sampleFromObserver\"," \
  " \"-sampleFromAllSides\" or \"-sampleFromLights\" is given," \
  " assumes all three are given.\n" \
  "\n" \
  "  -sampleFromLights\n" \
  "    This flag, if given, specifies that the origin of each initial" \
  " sampling ray may be any of the light sources.   If none of" \
  " the flags \"-sampleFromObserver\"," \
  " \"-sampleFromAllSides\" or \"-sampleFromLights\" is given," \
  " assumes all three are given.\n" \
  "\n" \
  "  -secondarySamples {N_GENS} {N_RAYS}\n" \
  "    This optional parameter specifies the number {N_GENS} of" \
  " additional generations of sampling sites to be selected" \
  " after the initial sites.  Each new generation is obtained" \
  " by casting {N_RAYS} rays from each of the previously" \
  " selected sites.  If this parameter is not specified, the" \
  " program assumes {N_GENS = N_RAYS = 0} (that is, the sampling" \
  " sites are restricted to the initial ones)."

#endif