UImportanceSamplingLibrary::ImportanceSample
#include "Kismet/ImportanceSamplingLibrary.h"
Access: public
Specifiers: staticUFUNCTIONBlueprintPure
Description
Draws a single importance-weighted sample position from a precomputed FImportanceTexture, biasing toward brighter (or otherwise higher-weighted) regions of the source texture. Commonly used to place many point lights or particles so their density matches a texture's luminance.
Caveats & Gotchas
- • Rand must come from a well-distributed 2D source (e.g. RandomSobolCell2D or NextSobolCell2D) for the resulting samples to be well spread — using the same Rand repeatedly clusters all samples at one point.
- • Samples and Intensity are used purely for normalizing SampleIntensity across the whole batch; passing an incorrect Samples count will scale every sample's intensity incorrectly relative to the intended total.
- • This function only produces one sample per call — looping it for many samples means calling MakeImportanceTexture once and ImportanceSample many times, not rebuilding the FImportanceTexture each iteration.
Signature
static void ImportanceSample(const FImportanceTexture &Texture, const FVector2D &Rand, int Samples, float Intensity, FVector2D &SamplePosition, FLinearColor &SampleColor, float &SampleIntensity, float &SampleSize)Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| Texture | const FImportanceTexture& | Precomputed importance data from MakeImportanceTexture. | — |
| Rand | const FVector2D& | Random 2D point with components evenly distributed between 0 and 1, used to drive the sample. | — |
| Samples | int | Total number of samples that will be used overall, for intensity normalization. | — |
| Intensity | float | Total target intensity for the light/effect being distributed across all samples. | — |
| SamplePosition | FVector2D& | Outputs the importance-sampled 2D texture coordinate (0-1). | — |
| SampleColor | FLinearColor& | Outputs the representative color near SamplePosition. | — |
| SampleIntensity | float& | Outputs the intensity of this individual sample, scaled by probability and Samples. | — |
| SampleSize | float& | Outputs the local density of points near SamplePosition, scaled for 1x1 texture space. | — |
Return Type
void Example
Distribute point lights over a texture's bright areas C++
FImportanceTexture ImportanceTex = UImportanceSamplingLibrary::MakeImportanceTexture(MyTexture, EImportanceWeight::Luminance);
const int32 NumSamples = 32;
for (int32 i = 0; i < NumSamples; ++i)
{
const FVector2D Rand = UImportanceSamplingLibrary::RandomSobolCell2D(i, NumSamples);
FVector2D SamplePosition; FLinearColor SampleColor; float SampleIntensity; float SampleSize;
UImportanceSamplingLibrary::ImportanceSample(ImportanceTex, Rand, NumSamples, 1000.0f, SamplePosition, SampleColor, SampleIntensity, SampleSize);
// spawn a light at SamplePosition with SampleColor and SampleIntensity
}See Also
Tags
Version History
Introduced in: 5.0
| Version | Status | Notes |
|---|---|---|
| 5.6 | stable | — |
Feedback
Was this helpful?