Accessing Active Viewport Info, Type, and Transforms
 
 
 

The following 3ds Max system global variables are associated with the viewports:

viewport.activeViewport

Lets you get and set the index of the active viewport. If you change the currently active viewport to a 2D view, this variable will contain the value 0.

   

viewport.numViews

Contains the number of 3D viewports in the current viewport layout. This variable is read-only. This variable does not reflect any 2D (Track View, Schematic View, Listener, and so on) views in the viewport layout. So, for example, if viewport.getLayout() returns #layout_4 and this variable contains the value 2, you know that two of the viewports contain 2D views. MAXScript currently does not allow you to access 2D view viewports.

Viewport Layout

viewport.getLayout()   
viewport.setLayout<view_layout_name> 

Gets or sets the viewport layout, where <view_layout_name> specifies the viewport layout configuration. When setting the layout, the view shown in each viewport is based on the configuration set in Customize > Viewport Configuration > Layout.

The list of valid <view_layout_name> values below uses the following syntax:

# is the total number of viewports.
V = vertical split
H = horizontal split
L/R = left/right placement
T/B = top/bottom placement

The valid <view_layout_name> values are:

#layout_1-- 1 viewport #layout_2v -- 2 viewports, vertical split, both same size #layout_2h -- 2 viewports, horizontal split, both same size #layout_2ht -- 2 viewports, horizontal split, top smaller #layout_2hb-- 2 viewports, horizontal split, top larger #layout_3vl-- 3 viewports, 2 on left, 1 on right #layout_3vr -- 3 viewports, 1 on left, 2 on right #layout_3ht-- 3 viewports, 2 on top, 1 on bottom #layout_3hb-- 3 viewports, 1 on top, 2 on bottom #layout_4-- 4 viewports, all same size #layout_4vl -- 4 viewports, 3 on left, 1 on right #layout_4vr -- 4 viewports, 1 on left, 3 on right #layout_4ht-- 4 viewports, 3 on top, 1 on bottom #layout_4hb-- 4 viewports, 1 on top, 3 on bottom 

   

viewport.getType [ index:<integer> ] 
viewport.setType <name> 

Get and set the view type for the current viewport. Valid <name> values are:

#view_top-- Top #view_bottom -- Bottom #view_right-- Right #view_left-- Left #view_front -- Front #view_back-- Back #view_persp_user -- Perspective #view_iso_user-- User #view_camera-- Camera #view_spot -- Light  #view_shape -- Shape #view_grid-- Grid 

If the optional index: keyword is specified in 3ds Max 2009 and higher, viewport.getType()will return the type of the indexed viewport instead of the active viewport type. The index numbers correspond to the ones used by viewport.activeViewport.

NOTES:

If the current viewport is an extended viewport (that is, a Schematic View, Asset Manager, or MAXScript Listener viewport), getType() will return undefined. If a Camera is specified with setType(), and there is not exactly one camera selected, a dialog will be displayed for the user to select the camera to use. If there is no Camera, a message box "No Cameras in scene" will be issued.

viewport.getType can also return a value of #view_none. If none of the viewports have focus, a value of false is returned.

viewport.setType returns a boolean - true if setting the view type was successful, false if not.

EXAMPLE

viewport.setType #view_top -- set active viewport to Top view
--> true
viewport.getType() -- should return what you expect...
--> #view_top

   

viewport.GetID <viewportIndex> 

Returns the ID of the indexed viewport in 3ds Max 2009 and higher. The ID cannot be set.

When a viewport is maximized, its index is always 1, and its ID corresponds to its index when not maximized.For example, if the bottom right viewport with index 4 is maximized, its index will become 1, but its ID will remain 4.

   

viewport.ResetAllViews() 

This function will reset all viewports in 3ds Max to the default layout.

   

getActiveCamera() 

viewport.getCamera [index:<integer>] 

Return the camera node associated with the active view if any, undefined if none.

If the optional index: keyword is specified in 3ds Max 2009 and higher, viewport.getCamera() returns the camera of the indexed viewport instead of the active viewport. The index numbers correspond to the ones used by viewport.activeViewport.

   

viewport.setCamera <camera_or_light_node> 

Sets the active viewport to a Camera view, using the specified camera.

You can also set the active view to a Light view using a free, target or direct light.

   

viewport.CanSetToViewport() 

Returns true for cameras and lights that can be used as a viewport camera (valid argument toviewport.setCamera)

   

Viewport Display and Render Controls

viewport.setGridVisibility {<int> | #all} <bool> 

Set whether the grid is visible in a viewport, where <int> is the viewport index, and <bool> is the grid visibility state. If #all is specified, the grid visibility for all viewports is set to the specified state.

   

viewport.getGridVisibility <int> 

Get whether the grid is visible in a viewport, where <int> is the viewport index.

   

viewport.isWire() 

Returns true if the active viewport is in Wire mode

   

viewport.DispBkgImage

When this variable isset to true, the background image will be displayed in the active viewport. When set to false, the background image will not be displayed.

   

viewport.GetRenderLevel() 

Returns the viewport render level.

The return value can be one of the following: #smoothhighlights, #wireFrame, #smooth, #facethighlights, #facet, #flat, #litwireframe, #Box, #hiddenline

   

viewport.SetRenderLevel <render_level> 

Sets the current viewport's render level to the specified mode.

Valid argument values are #smoothhighlights, #wireFrame, #smooth, #facethighlights, #facet, #flat, #litwireframe, #Box, #hiddenline

   

viewport.GetShowEdgeFaces() 

Returns true if Edged Faces are enabled in the current viewport, false otherwise.

   

viewport.SetShowEdgeFaces <boolean> 

Turns the Edged Faces display on or off depending on the boolean argument.

   

viewport.GetTransparencyLevel() 

Returns the current viewport's transparency level. Possible values are:

1 - None

2 - Simple

3 - Best

   

viewport.SetTransparencyLevel <transp_level> 

When Sets the current viewport's transparency level. See above for possible values.

   

viewport.IsEnabled() 

Returns true if the current viewport is enabled, false if it is disabled.

   

viewport.IsPerspView() 

Returns true if the current viewport is a perspective viewport (Pespective or non-othographic Camera), false if it is an orthographic view (Top, Bottom, Front, Back, Left, Right, User, orthographic Camera...).

   

viewport.GetFPS() 

Returns the last frame rate value in frames per second calculated by the Show Statistics overlay for the current viewport. If the viewport's Show Statistics option is not turned on, the value will not represent the current frame rate of the viewport.

Available in 3ds Max 9 and higher.

In 3ds Max 2008 and higher, if the Adaptive Degradation is turned on, the value reported will be the target frame rate, not the actual frame rate.

   

Viewport Transformations

<matrix3>getViewTM() <matrix3>viewport.getTM() viewport.setTM <matrix3> 

Get or set the active view screen-to-world transform matrix for non-orthographic (perspective and isometric user views) viewports. This is the affine camera or viewport matrix. setTM only operates on Perspective viewports, and returns a value of true if the view transform matrix was successfully set, false otherwise.

The following function returns as a Ray value the "eye" location and direction for the active viewport. The viewport needs to be anon-orthographic viewport.

EXAMPLE

fn getViewDirectionRay =
(
-- The affine TM transforms from world coords to view coords-- so we need the inverse of this matrix
local coordSysTM = Inverse(getViewTM())
-- The Z axis of this matrix is the view direction.
local viewDir = -coordSysTM.row3
-- get the view position from this matrix
local viewPt = coordSysTM.row4
return ray viewPt viewDir
)

   

getViewFOV() 

Returns the Field of View for the active viewport. If the viewport is an orthographic viewport, a value of 57.2958 degrees (1 radian) is returned.

   

viewport.GetFOV() 

Returns the Field of View for the active viewport. Same as getViewFOV()

   

viewport.SetFOV <float> 

Sets the Field of View for the active viewport to the specified angle in degrees.

Works only with perspective and camera views.

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

   

<float>viewport.getFocalDistance() 

Return the focal distance of the active viewport if a perspective view, undefined otherwise.

Available in 3ds Max 2008 and higher.

   

<boolean>viewport.setFocalDistance() 

Sets the focal distance of the active viewport.

Works only with perspective views, does not work with camera views.

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

   

<boolean>viewport.pan <float> <float> 

Performs a pan of the current viewport using the first argument as the X and the second argument as the Y screen delta in pixels.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

viewport.pan 10 0 -- pan horizontally by ten pixel
completeredraw() -- redraw the views to see the changes

   

viewport.zoom <float> 

Performs a zoom of the current viewport using the supplied float value as zoom factor- for example, 2.0 zooms out two times, 0.5 zooms in two times.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

--while the perspective viewport is active, evaluate
viewport.setFOV 50.0 --set viewport Field Of View to 50 deg.
true
completeredraw() --redraw the views
OK
viewport.zoom 2.0 --zoom out two times
true
completeredraw() --redraw the views
OK
viewport.getFOV() --get the new Field Of View
86.0061
--What does this result mean?--The FOV angle is dependent on the width of the image plane,--but the target distance remains the same.--When the angle is 50 degrees,tangens of half the angle is--tan (50.0/2) -> 0.466308--When you zoom in two times, thewidthincreasestwice.--Thus, atan(0.466308*2) -> 43.0031 (newhalf-angle) and--43.0031 * 2 =86.0062which is thefullviewport FOV angle:
 

   

<boolean>viewport.zoomPerspective <float> 

Zooms the active viewport. Exactly equivalent to the Interactive Zoom tool in the 3ds Max UI.

This method only works with Perspective views. Does not work for camera views. In the 3ds Max UI, when a user zooms in an orthographic or Isometric User view, internally, a switch is performed on the viewport type, and instead a call to ViewExp::Zoom (viewport.zoom())is made.

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

   

<boolean>viewport.rotate <quat> [center:<Point3>] 

Performs a rotate of the current viewport using the supplied quaternion value for the rotation and the Point3 value as the center to perform the rotation about.

Works with all viewport types except object-based ones (Camera, Light etc.).

Returns true if successful, false otherwise.

Available in 3ds Max 2008 and higher.

FOR EXAMPLE

theAxis = (viewport.getTM()).row3
for i = 1 to 180 do
(
viewport.rotate (quat 2 theAxis)
completeredraw()
)

   

<bitmap>viewport.getViewportDib() 

This method returns the active viewport's graphics window image as a Bitmap value. The size of the bitmap is the same size as the viewport. This method is different from gw.getViewportDib() documented here in that it includes the results of using maxops.displayActiveCameraViewWithMultiPassEffect(). Thus, it can be used to generate viewport images containing Depth Of Field or Motion Blur previews.

Available in 3ds Max 2008 and higher. Previously available in Avguard Extensions.

   

viewport.ZoomToBounds <All_Bool> <A_Point3> <B_Point3> 

Zooms all or the current viewport to a bounding region.

When the first argument is passed as true, all viewports are zoomed. When false, only the selected viewport is zoomed.

The second and third arguments define the bounding region to zoom to.

   

<point2>getViewSize() 

Returns the active view size as point2 in pixels.

   

<float>getScreenScaleFactor <point3> 

Returns the active view scale factor, giving the width in world-space units at the point's distance from the view space origin.

   

<float>viewport.GetScreenScaleFactor() 

Returns the active view scale factor, giving the width in world-space units at the point's distance from the view space origin. Same as getScreenScaleFactor()

   

<ray>mapScreenToWorldRay <pixel_coord_point2> 

Returns a Ray value in world space through the given viewport pixel coordinates in the current active view, and perpendicular to the viewport plane.

   

<point3>mapScreenToView <pixel_coord_point2> <depth_float> \ [ <viewport_size_point2> ] 

Returns a 3D point in the view coordinate space. Given a point in the active viewport screen (in viewport pixel coordinates), and a depth in view coordinates, this method maps the point into view coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

   

<point3>mapScreenToCP <pixel_coord_point2> [ <viewport_size_point2> ] 

Maps viewport pixel coordinates in the current active view to the construction plane in world coordinates. If <viewport_size_point2> is supplied, the specified viewport size is used instead of the actual viewport size.

   

<matrix3>getCPTM() 

Returns the construction-plane-to-world transformation matrix.

   

<float>gw.nonScalingObjectSize() 

The value returned from this method may be used as a scale factor that will counteract the viewport zoom. For example, lights, cameras, and tape helper objects use this factor so the size of the node in the scene remains constant when the viewport is zoomed in and out.

This value is affected by the 'Non-Scaling Object Size' spinner in the Viewport Preferences dialog, so the user has some control over this as well.

   

<point3>gw.getPointOnCP <pixel_coord_point2> 

Returns a point in world space on the current construction plane based on the specified screen coordinate.

   

<float>gw.getCPDisp <base_point3> <dir_point3> <start_pixel_coord_point2> <end_pixel_coord_point2> 

This method returns a length in world space given a start screen point (<start_pixel_coord_point2>), an end screen point (<end_pixel_coord_point2>), a base point (<base_point3>) and a direction vector (<dir_point3>). For example, when creating a cylinder, the user clicks the mouse down to define the center point of the cylinder (base), then drags out a radius. They then drag out a height for the cylinder. This method is used to return intermediate and final heights for the cylinder based on the initial base point, the direction vector (the Z axis), the start mouse point, and the current point the user is interactively adjusting.

   

<float>gw.getVPWorldWidth <point3> 

Returns the viewport screen width factor in world space at a point in world space.

   

<point3>gw.mapCPToWorld <point3> 

Returns the corresponding world space point given a point on the construction plane. For example, if you use gw.getPointOnCP() to convert a screen coordinate to a point on the construction plane, you could then call this method to convert that point on the construction plane to a world space point.

   

<float>gw.getFocalDist() 

Returns the focal distance of an active perspective view.

   

<boolean>gw.IsPerspView() 

Returns true if the active viewport is a perspective view; otherwise returnsfalse.

   

Viewport Snapping

<point3>gw.snapPoint<pixel_coord_point2> [ snapType:<snapType_name> ] [ snapPlane:<matrix3> ] 

Given a 2D screen coordinate, this method returns a 3D point on either the current construction plane or the optional snapPlane based on the current snap settings and the optional snapType: parameter.

The valid <snapType_name> values are:

#in3d - Snap to all points.

#inPlane - Snap only to points on the construction plane.

#unSelObjs - Ignore selected nodes when considering snap points.

#selObjs - Ignore unselected nodes when considering snap points.

#unSelSubobj - Ignore selected sub-object geometry when considering snap points.

#selSubobj - Ignore unselected sub-object geometry when considering snap points.

#force3d - Override user settings to force snap in 3D.

The optional snapPlane: argument available in 3ds Max 8 and higher is a matrix3 value which is the transform that maps the XY plane to the snapping plane. If the matrix3 value supplied is equal to the identity matrix (Matrix3 1), the snapping plane is identical to the XY construction plane.

EXAMPLE

tm = Matrix3(1) --represents the XY plane
m = Point2 0 0 --screen pixel coordinates
p = gw.snapPoint m snapPlane:tm --returns the snapping point

   

<float>gw.snapLength <length_float> 

This method snaps the length to the nearest snap increment and returns the snapped distance.

   

Viewport Regions

viewport.setRegionRect <viewport index> <box2> 

Set the region rectangle for the specified viewport.

   

viewport.getRegionRect <viewport index> 

Get the region rectangle for the specified viewport.

   

viewport.setBlowupRect <viewport index> <box2> 

Set the blowup rectangle for the specified viewport. The blowup rectangle must have the same aspect as the current render output size aspect. The top, bottom, and left component values are taken from the Box2 value argument, but the right component value is re-calculated to force the proper aspect.

   

viewport.getBlowupRect <viewport index> 

Get the blowup rectangle for the specified viewport.

You can use the Interface: EditRenderRegion to control the manual region editing gizmo in 3ds Max 2009 and higher.

See Also