Table of Contents

Class GPUVideoEffectVR360Base

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

Represents a base class for GPU-accelerated VR 360-degree video effects that provide viewport control and perspective transformation.

public class GPUVideoEffectVR360Base : GPUVideoEffect, IGPUVideoEffectVR360Base, IGPUVideoEffect

Inheritance

Derived

Implements

Inherited Members

Remarks

The VisioForge.Core.Types.VideoEffects.GPUVideoEffectVR360Base class serves as the foundation for 360-degree video projection effects that convert spherical or specialized 360-degree video formats into flat, viewable perspectives. This base class provides common camera controls (yaw, pitch, roll) and field of view (FOV) parameters shared by all 360-degree video transformation effects. Derived classes implement specific projection mappings for different 360-degree video formats such as equirectangular and equiangular cubemap layouts.

SDK Availability

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

GPU Acceleration

All VR 360 effects derived from this base class are GPU-accelerated using custom shader programs that perform real-time projection transformations. The shaders implement inverse mapping from output pixels to input texture coordinates on the spherical surface, enabling interactive camera control without pre-rendering. GPU processing ensures smooth 60+ FPS performance at 4K resolution for fluid VR viewing experiences.

Technical Concepts

  • Yaw: Horizontal rotation around vertical axis (left-right looking)
  • Pitch: Vertical rotation around horizontal axis (up-down looking)
  • Roll: Rotation around forward axis (tilting head left-right)
  • FOV (Field of View): Angular extent of visible area (simulates zoom)
  • Coordinate systems follow standard aviation/3D graphics conventions
  • All transformations performed in GPU shader for real-time responsiveness

Common Use Cases

  • Converting 360-degree videos to flat viewing format for traditional displays
  • Interactive VR video players with mouse or sensor-based camera control
  • Extracting specific viewpoints from 360-degree footage for editing
  • Creating guided tours through 360-degree video content
  • Reframing 360-degree video for social media or broadcast
  • Converting immersive video to conventional formats

Camera Control Parameters

The camera orientation is controlled through three rotation angles (yaw, pitch, roll) measured in degrees. These rotations define where the virtual camera is looking within the 360-degree spherical environment:

  • Yaw (0-360°): Pan left/right - 0° faces forward, 90° faces right, 180° faces backward, 270° faces left
  • Pitch (-90 to +90°): Tilt up/down - 0° looks straight ahead, +90° looks straight up, -90° looks straight down
  • Roll (-180 to +180°): Rotate camera around viewing axis - 0° is level, ±90° is sideways
  • FOV (30-120°): Wider angles show more of scene, narrower angles zoom in

Field of View Guidelines

  • 30-50°: Telephoto look, zoomed in, narrow perspective
  • 60-70°: Standard viewing angle, natural perspective
  • 80-90° (default 80°): Wide angle, immersive viewing
  • 100-120°: Ultra-wide, fish-eye style, peripheral vision coverage

Performance Characteristics

VR 360 projection effects are computationally intensive due to per-pixel coordinate transformation and texture sampling. However, GPU shader implementation ensures real-time performance suitable for interactive applications. The effects support dynamic parameter updates (yaw, pitch, roll, FOV) without frame drops, enabling smooth camera movement. Bilinear or bicubic texture filtering maintains image quality during projection transformations.

Inheritance Hierarchy

This base class should not be instantiated directly. Use derived classes for specific 360-degree formats:

  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360: For standard equirectangular 360° videos
  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360: For equiangular cubemap format videos

Integration Notes

For interactive VR video applications, update yaw, pitch, and roll parameters in response to user input (mouse movement, touch gestures, VR headset sensors) to create immersive viewing experiences. Smooth interpolation between rotation values prevents jerky camera movement. FOV can be adjusted dynamically to implement zoom functionality. The effects work with any video player that supports real-time parameter updates.

Related Effects

  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360: Derived class for equirectangular projection
  • VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360: Derived class for cubemap projection

Constructors

GPUVideoEffectVR360Base(bool, float, float, float, float, string, TimeSpan, TimeSpan)

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

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

Parameters

enabled bool

true to enable the VR 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 forward. 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 horizon. Controls up-down tilt of the camera view. Positive values look up, negative values look down.

roll float

The initial roll angle in degrees for rotation around viewing axis (-180 to +180°). Default is 0°, level horizon. Controls camera tilt around the forward axis. Non-zero values create tilted or rotated perspective.

fov float

The initial field of view angle in degrees (30-120°). Default is 80°, providing balanced immersive viewing. Controls zoom level - lower values zoom in (telephoto), higher values zoom out (wide-angle).

name string

A unique identifier for this effect instance. Defaults to "VR360". This name can be used to retrieve the effect interface from the effect collection for runtime control and camera parameter modification. Use descriptive names when managing multiple 360 video effects (e.g., "MainCamera", "OverviewView").

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 VR viewing control for creating guided camera paths through 360-degree content.

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 effects for switching between 360 and flat video modes.

Remarks

This base class constructor should not be called directly in typical usage. Instead, instantiate one of the derived classes (VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360 or VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360) that implement specific projection mappings for different 360-degree video formats.

The camera orientation parameters (yaw, pitch, roll) and field of view can be updated at runtime to create interactive VR viewing experiences. All transformations are GPU-accelerated for smooth, responsive camera control.

Properties

Fov

Gets or sets the field of view angle for controlling zoom and perspective.

public float Fov { get; set; }

Property Value

float

Remarks

Field of view determines how much of the 360-degree scene is visible in the output frame. It directly controls the zoom level - smaller FOV values zoom in (showing less of the scene with more detail), while larger values zoom out (showing more of the scene with less detail).

Typical FOV ranges for different effects:

  • 30-50°: Telephoto, zoomed-in, narrow perspective (good for focusing on details)
  • 60-70°: Natural human vision equivalent, standard viewing angle
  • 80-90°: Wide-angle, immersive VR viewing (default 80°)
  • 100-120°: Ultra-wide, peripheral vision coverage, fish-eye effect

FOV can be adjusted dynamically to implement interactive zoom functionality in VR video players. Very wide FOV values (>100°) may introduce noticeable distortion at frame edges.

Pitch

Gets or sets the pitch angle for vertical camera rotation.

public float Pitch { get; set; }

Property Value

float

Remarks

Pitch controls the vertical tilt of the virtual camera, determining whether the view is looking up, down, or at the horizon. This is mapped to vertical mouse movement or head tracker Y-axis rotation. Extreme pitch values (near ±90°) may exhibit distortion at the poles of the spherical projection, which is characteristic of spherical coordinate systems.

Roll

Gets or sets the roll angle for rotation around the viewing axis.

public float Roll { get; set; }

Property Value

float

Remarks

Roll controls the rotational tilt of the camera around its viewing axis, similar to tilting your head to the side. This parameter is less commonly used in interactive VR applications as it can cause disorientation, but is useful for stabilization correction or creative effects. In most VR viewing scenarios, roll should remain at 0° for comfortable viewing.

Yaw

Gets or sets the yaw angle for horizontal camera rotation.

public float Yaw { get; set; }

Property Value

float

Remarks

Yaw controls the horizontal panning direction of the virtual camera within the 360-degree environment. This is the primary control for looking left and right. In interactive applications, yaw is typically mapped to horizontal mouse movement or head tracker X-axis rotation. Smooth interpolation between yaw values creates fluid panning motion.

Methods

GetEffectType()

Gets the GPU video effect type identifier for this VR 360 effect.

public GPUVideoEffectType GetEffectType()

Returns

GPUVideoEffectType

This method throws an exception as the base class does not represent a concrete effect type. Derived classes must override this method to return their specific effect type identifier.

Remarks

This method exists to enforce the abstract behavior of the base class within the non-abstract class hierarchy. Implementations in derived classes return specific values such as VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.EquiRectangular360 or VisioForge.Core.Types.VideoEffects.GPUVideoEffectType.EquiAngularCubemap360.

Exceptions

Exception

Always throws an exception requesting the use of a derived class implementation. Call this method on VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquirectangular360 or VisioForge.Core.Types.VideoEffects.GPUVideoEffectEquiangularCubemap360 instances instead.