package fluvial

import "salty/terrain/internal/world"

// Deterministic per-cell jitter, and why a router needs one.
//
// D8 lets a cell drain to one of eight neighbours, so every channel is a chain of 0, 45 and 90 degree
// segments. In mountains the slope hides it. On a plain it is the dominant artefact, and for a specific
// reason: across a filled flat the only gradient present is the priority-flood's own epsilon, one millimetre
// a cell, applied in the order the flood happened to reach the cells. The router then faithfully follows the
// flood's traversal geometry and draws it as rivers — ruler-straight diagonals, the polygonal network that
// killed the first attempt at flat plains.
//
// The fix is to stop the epsilon being uniform. A hash scatters it by plus or minus half, which is far below
// anything that matters to the solve (a millimetre against metre-scale relief) and far above the difference
// the flood's ordering would otherwise leave, so the descent direction on a flat is decided by the hash
// rather than by scan order. The same hash breaks near-ties between two equally steep neighbours, which is
// the other place a fixed direction order leaks a grid axis into the result.
//
// It is a hash rather than a random source because cross-cutting rule 12 is determinism from a seed: the
// value for a cell must not depend on how many cells were visited before it, on which goroutine ran, or on
// how many steps the solve has taken.
//
// And it is a hash of a *world position* rather than of a grid index, which is rule 1 of the tiling plan in
// Docs/Terrain-Next.md 3.3. A planet is solved one landmass at a time, so the same physical cell turns up in
// grids of different widths at different offsets; keyed on the index it would jitter differently each time,
// and every place two frames met would show it. Keyed on where the cell actually is, it cannot.

// The k namespace. Every caller of hashXY picks a k, and two callers that share one get perfectly correlated
// jitter - the clamp's allowance would track the router's tie-break in the same direction, which is exactly
// the kind of hidden coupling that prints a texture nobody can attribute. They are named here so a new
// caller has to pick a free one.
const (
	jitterFloodEpsilon int32 = 0  // the priority-flood's per-cell fall across a flat (fluvial.go)
	jitterReceiverTie  int32 = 1  // .. 8, one per D8 direction: the steepest-neighbour tie-break (fluvial.go)
	jitterReposeAllow  int32 = 9  // .. 16, one per D8 direction: the repose clamp's allowance (repose.go)
	jitterReposeOrder  int32 = 17 // the repose clamp's pop order (repose.go)
)

// hashXY is splitmix64's finaliser over a weighted sum of the seed and the position. One finalising round,
// because this is called eight times per cell per step - several hundred billion times over a planet bake -
// and the requirement is only that neighbouring cells get unrelated values, not cryptographic quality. The
// three odd constants are summed rather than exclusive-ored so that swapping x and y does not collide.
func hashXY(seed uint64, x, y, k int32) float32 {
	h := seed ^ (uint64(uint32(x))*0x9e3779b97f4a7c15 +
		uint64(uint32(y))*0xc2b2ae3d27d4eb4f +
		uint64(uint32(k))*0x165667b19e3779f9)
	h ^= h >> 30
	h *= 0xbf58476d1ce4e5b9
	h ^= h >> 27
	h *= 0x94d049bb133111eb
	h ^= h >> 31
	return float32(h>>11) / float32(1<<53)
}

// SetSeed ties the jitter to the run's seed, so two seeds do not share the same flat-routing geometry.
// Zero is a perfectly good seed; it is the default and nothing depends on it being set.
func (g *Grid) SetSeed(seed int64) { g.seed = uint64(seed)*0x9e3779b97f4a7c15 + 0x243f6a8885a308d3 }

// SetFrame says where on the planet this grid sits, which is what turns the jitter from an index hash into
// a position hash. Without it a grid is its own world at the origin, which is what the square canvas is and
// what every existing test expects, so it is optional and NewGrid does not require it.
func (g *Grid) SetFrame(f world.Frame) {
	g.originX = int32(f.P.WrapX(f.X0))
	g.originY = int32(f.Y0)
	g.planetW = int32(f.P.W)
}

// worldX and worldY map a grid cell to its planet cell.
//
// The wrap is a compare and a subtract rather than a modulo on purpose: originX is already inside the
// planet and x is less than the planet's width, so the sum overshoots by at most one turn. A modulo here
// would be a division in the router's innermost loop.
func (g *Grid) worldX(x int) int32 {
	v := g.originX + int32(x)
	if g.planetW > 0 && v >= g.planetW {
		v -= g.planetW
	}
	return v
}

func (g *Grid) worldY(y int) int32 { return g.originY + int32(y) }