[video][cuda][beta] decoder nvtx annotations

[vkhalidov]

Summary

Introduces USE_NVTX CMake flag, which, if enabled, defines USE_NVTX C++ preprocessor macro.
The USE_NVTX macro defined whether NVTX annotations shold be added to the cuda:beta interface of torchcodec. NVTX annotations facilitate reading and analyzing data collected by NSight profiler.

Profile With Annotations (this PR)

Command line:

nsys profile \
--trace=cuda,nvtx,nvvideo,osrt \
--cuda-memory-usage=true \
--capture-range=none \
--sample=none \
-o nsight_report \
python3 <script> <arg0> <arg1> ...

Profile (note NVTX annotations related to decoder instantiation and frames decoding):

Profile Without Annotations (before)

Same command line, profile (no NVTX annotations):

Note: used NSight 2026.1.1 to visualize both profiles

Test Plan

1. Tested torchcodec build with NVTX annotations enabled via an environment variable:

USE_NVTX=1 ENABLE_CUDA=1 pip install -e . --no-build-isolation -vv

and verified CMake cache entry:

//Enable NVTX annotations for profiling (requires CUDA)
USE_NVTX:BOOL=ON

Used this build to produce profile with NVTX annotations.

2. Tested torchcodec build with NVTX annotations enabled via an environment variable, but disabled by CMake when ENABLE_CUDA is not set:

USE_NVTX=1 pip install -e . --no-build-isolation -vv

Observed the following message on build:

  CMake Warning at src/torchcodec/_core/CMakeLists.txt:17 (message): 
  USE_NVTX requires ENABLE_CUDA=ON.  Disabling USE_NVTX.

and the following entry in CMakeCache.txt:

//Enable NVTX annotations for profiling (requires CUDA)
USE_NVTX:BOOL=OFF

3. Tested torchcodec build with NVTX annotations not enabled explicitly, with ENABLE_CUDA=1:

ENABLE_CUDA=1 pip install -e . --no-build-isolation -vv

and verified the CMake cache entry:

//Enable NVTX annotations for profiling (requires CUDA)
USE_NVTX:BOOL=OFF

4. Tested torchcodec build without any environment variables:

pip install -e . --no-build-isolation -vv

and verified the CMake cache entry:

//Enable NVTX annotations for profiling (requires CUDA)
USE_NVTX:BOOL=OFF

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/meta-pytorch/torchcodec/1228

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

✅ No Failures

As of commit 3693a8f with merge base 5800d58 ():
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.