/* osgEarth
 * Copyright 2025 Pelican Mapping
 * MIT License
 */

#ifndef OSGEARTHSYMBOLOGY_INSTANCE_SYMBOL_H
#define OSGEARTHSYMBOLOGY_INSTANCE_SYMBOL_H 1

#include <climits>

#include <osgEarth/Common>
#include <osgEarth/Symbol>
#include <osgEarth/Tags>
#include <osgEarth/Expression>
#include <osg/Vec3f>

namespace osgEarth
{
    class IconSymbol;
    class ModelSymbol;
    namespace Util {
        class InstanceResource;
    }

    /**
     * Base class for symbols that represent an instance of an external resource
     * like an icon or a model and can be placed at a location.
     */
    class OSGEARTH_EXPORT InstanceSymbol : public TaggableWithConfig<Symbol>
    {
    public:
        /**
         * Controls the placement of the instance.
         */
        enum Placement
        {
            /** Places an instance at each feature point (default) */
            PLACEMENT_VERTEX,

            /** Places one instance at the centroid of the feature. */
            PLACEMENT_CENTROID,

            /** Places instances at regular intervals within/along the feature geometry,
                according to density. */
            PLACEMENT_INTERVAL,

            /** Scatter instances randomly within/along feature, according to density. */
            PLACEMENT_RANDOM
        };

    public:

        InstanceSymbol(const InstanceSymbol& rhs,const osg::CopyOp& copyop=osg::CopyOp::SHALLOW_COPY);

        /** dtor */
        virtual ~InstanceSymbol() { }

        /** URI of the instance to use for substitution. */
        OE_OPTION(Expression<URI>, url, {});

        /** How to map feature geometry to instance placement. (default is PLACEMENT_CENTROID) */
        OE_OPTION(Placement, placement, PLACEMENT_VERTEX);

        /** For PLACEMENT_RANDOM/INTERVAL, the scattering density in instances per sqkm */
        OE_OPTION(float, density, 25.0f);

        /** Model instance scale factor */
        OE_OPTION(Expression<float>, scale, 1.0f);

        /** Seeding value for the randomizer */
        OE_OPTION(unsigned, randomSeed, 0u);

        /** URI alias map for embedded resources */
        OE_OPTION(URIAliasMap, uriAliasMap, {});

        ///** Expression that returns custom geometry as a GeoJSON string. 
        //    You will typically use this as a script that takes the input geometry
        //    to dumps out a new geometry for model substitution. */
        //optional<StringExpression>& script() { return _script; }
        //const optional<StringExpression>& script() const { return _script; }

    public: // conversions to built-in base classes, for convenience.

        const IconSymbol* asIcon() const;
        const ModelSymbol* asModel() const;

    public:
        virtual Config getConfig() const;
        virtual void mergeConfig( const Config& conf );

    public: // internal
        /** Creates a new (empty) resource appropriate for this symbol */
        virtual InstanceResource* createResource() const =0;

    protected:
        InstanceSymbol( const Config& conf =Config() );
    };
} // namespace osgEarth

#endif // OSGEARTHSYMBOLOGY_MARKER_SYMBOL_H
