Table of Contents

Class GPUVideoEffectEquiangularCubemap360

Namespace
VisioForge.Core.Types.VideoEffects
Assembly
VisioForge.Core.dll

Represents a GPU-accelerated equiangular cubemap 360-degree video effect that converts cubemap-based panoramic video to flat perspective view.

public class GPUVideoEffectEquiangularCubemap360 : GPUVideoEffectVR360Base, IGPUVideoEffectEquiangularCubemap360, IGPUVideoEffectVR360Base, IGPUVideoEffect

Inheritance

Implements

Inherited Members

Remarks

The VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360 effect transforms equiangular cubemap format 360-degree video into a flat, viewable perspective. Equiangular cubemap (EAC) is an optimized 360-degree video format developed by Google that provides better pixel density distribution and sampling efficiency compared to traditional equirectangular projection. The format divides the sphere into six faces arranged as a cubemap with equiangular sampling within each face, reducing over-sampling at poles and providing more uniform resolution across the sphere. This effect provides the same interactive camera controls (yaw, pitch, roll, FOV) as other VR 360 effects.

SDK Availability

  • Video Capture SDK .Net: Yes
  • Video Edit SDK .Net: Yes
  • Media Player SDK .Net: Yes
  • Media Blocks SDK .Net: Yes

GPU Acceleration

This effect uses specialized GPU shaders that perform inverse equiangular cubemap projection in real-time. The shader determines which cubemap face to sample based on viewing direction, computes equiangular texture coordinates within that face, and applies camera rotation transformations. GPU parallel processing enables smooth 60+ FPS performance at 4K resolution. The cubemap sampling optimization reduces texture fetches compared to equirectangular, potentially improving performance and cache efficiency on some GPU architectures.

Technical Details

  • Converts equiangular cubemap (EAC) projection to rectilinear perspective projection
  • Source video contains six cubemap faces with equiangular sampling
  • Typical layout: 3x2 grid of faces (front/right/back/left/top/bottom)
  • Equiangular sampling provides more uniform pixel density than linear cubemaps
  • Reduces over-sampling at cube edges and poles compared to equirectangular
  • Implements cube face selection, equiangular coordinate transformation, and rotation
  • Supports dynamic camera control for interactive VR viewing

Common Use Cases

  • Playing YouTube 360 EAC format videos with optimized quality
  • Processing footage from cameras that output cubemap formats
  • High-quality VR video playback with improved pole region quality
  • Converting EAC 360° videos to flat perspectives for editing
  • Real-time VR video playback with reduced texture bandwidth
  • Interactive panoramic video viewing with optimized sampling

Equiangular Cubemap Format Characteristics

  • Six cube faces arranged in 3x2 or alternative layout patterns
  • Each face uses equiangular projection (equal angle increments)
  • More uniform resolution distribution across sphere than equirectangular
  • Reduced over-sampling at poles (where equirectangular stretches)
  • Typically 25-30% better coding efficiency than equirectangular
  • Commonly used by YouTube for high-quality 360° video streaming
  • Face boundaries handled seamlessly by shader interpolation

Performance Characteristics

Equiangular cubemap projection can be more efficient than equirectangular on some GPU architectures due to better texture cache coherency. The cubemap structure allows the GPU to sample from a smaller region of texture memory for any given view direction. At 1080p output resolution, frame processing time is typically 1-2ms on modern GPUs. At 4K resolution, performance remains real-time (60+ FPS) on mid-range and higher GPUs. The effect benefits from GPU texture units optimized for cubemap sampling.

Advantages Over Equirectangular

  • Better quality: More uniform pixel density, less polar stretching
  • Efficient encoding: 25-30% better compression efficiency
  • Reduced artifacts: Fewer distortions at extreme viewing angles
  • Better sampling: Equiangular projection optimizes quality per pixel
  • Pole quality: Superior image quality when looking up or down

Camera Control Integration

Camera controls work identically to equirectangular projection. Bind yaw, pitch, and roll properties to user input:

  • Mouse/Touch: Drag for yaw/pitch camera control
  • VR Headset: Read orientation from head tracking devices
  • Gamepad: Analog stick for camera rotation, triggers for zoom
  • Mobile Gyro: Device orientation for phone-based VR viewing

Apply smooth interpolation to prevent jerky camera motion and potential motion sickness.

Integration Tips

  • Verify source video is EAC format (typically 3:2 aspect ratio for standard layout)
  • Start with FOV of 80-90° for natural, immersive viewing experience
  • Note improved quality at pole regions compared to equirectangular sources
  • Face boundaries are handled automatically by the shader - no visible seams
  • Works best with EAC-encoded sources - conversion from other formats may lose quality

Format Detection and Compatibility

Equiangular cubemap videos can be identified by their aspect ratio (often 3:2) and metadata indicating EAC format. YouTube uses this format for high-quality 360° video. If you're unsure of source format, equirectangular (VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360) is more universally compatible but may have lower quality at poles. Using the wrong projection effect for a given format will result in distorted or incorrectly mapped output.

Limitations and Considerations

  • Source must be true EAC format - incompatible with standard equirectangular
  • Very wide FOV (>100°) may show artifacts at cube face boundaries
  • Less common than equirectangular - ensure source compatibility
  • Format detection is important - wrong projection causes distortion

Comparison with Equirectangular

Choose equiangular cubemap (VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360) when:

  • Source video is in EAC format (YouTube high-quality 360°)
  • Viewing quality at poles is important for your content
  • You need the best possible quality per bit/pixel

Choose equirectangular (VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360) when:

  • Source is standard spherical/lat-long format (most common)
  • Maximum compatibility is required
  • Source format is unknown or varied

Related Effects

  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectVR360Base: Base class providing common VR 360 functionality
  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360: For standard equirectangular format videos

Constructors

GPUVideoEffectEquiangularCubemap360(bool, float, float, float, float, string, TimeSpan, TimeSpan)

Initializes a new instance of the VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360 class with specified camera parameters and timing.

public GPUVideoEffectEquiangularCubemap360(bool enabled, float yaw = 0, float pitch = 0, float roll = 0, float fov = 80, string name = "EquiangularCubemap", TimeSpan startTime = default, TimeSpan stopTime = default)

Parameters

enabled bool

true to enable the equiangular cubemap 360 effect immediately; false to create the effect in a disabled state. The effect can be enabled or disabled later using the VisioForge.Core.Types.VideoEffects.GPUVideoEffect.Enabled property.

yaw float

The initial yaw angle in degrees for horizontal camera rotation (0-360°). Default is 0°, facing the front face of the cubemap. Controls left-right panning direction within the 360-degree environment.

pitch float

The initial pitch angle in degrees for vertical camera rotation (-90 to +90°). Default is 0°, looking at the horizon. Positive values look upward toward the top cubemap face, negative values look downward toward the bottom face.

roll float

The initial roll angle in degrees for rotation around viewing axis (-180 to +180°). Default is 0°, maintaining level horizon. Non-zero values create tilted perspective. Generally kept at 0° for comfortable VR viewing.

fov float

The initial field of view angle in degrees (30-120°). Default is 80°, providing balanced immersive viewing without excessive distortion. Lower values zoom in (telephoto), higher values zoom out (wide-angle). Typical comfortable range is 60-100° for VR applications.

name string

A unique identifier for this effect instance. Defaults to "EquiangularCubemap". This name can be used to retrieve the effect interface from the effect collection for runtime camera control and parameter modification. Use descriptive names when managing multiple camera views (e.g., "PrimaryView", "OverviewCam", "DetailCamera").

startTime TimeSpan

The time position in the video timeline when this effect should become active. Use Zero (the default) to apply the effect from the beginning of the video. Enables time-based activation for sequences that switch between 360° VR mode and flat video, or for creating guided tours with scripted camera movements.

stopTime TimeSpan

The time position in the video timeline when this effect should become inactive. Use Zero (the default) to apply the effect until the end of the video. When combined with startTime, creates time-windowed VR viewing segments within longer video projects.

Remarks

This effect transforms equiangular cubemap (EAC) format 360-degree video into flat rectilinear perspective view using GPU-accelerated projection. The equiangular cubemap format provides superior quality distribution and coding efficiency compared to traditional equirectangular projection. All camera parameters (yaw, pitch, roll, FOV) can be updated at runtime for interactive VR experiences. The shader automatically handles cubemap face selection and equiangular coordinate transformation.

Methods

GetEffectType()

Gets the specific GPU video effect type identifier for this equiangular cubemap 360 effect.

public GPUVideoEffectType GetEffectType()

Returns

GPUVideoEffectType

Returns VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.EquiAngularCubemap360, which uniquely identifies this effect as an equiangular cubemap-to-rectilinear projection effect in the GPU video effects pipeline.

Remarks

This method is used internally by the video processing pipeline to identify and route effects to the appropriate GPU shader implementations. The effect type determines which shader program is executed for performing the equiangular cubemap-to-plane projection transformation with optimized face selection and coordinate mapping.