Interface: IBitmapPager

The IBitmapPager Core Interface introduced in 3ds Max 2010 exposes settings related to the Bitmap Pager which has been extended to support an Automatic Limit Mode.

The Bitmap Pager UI has been completely removed from the Customize > Preferences > Render tab and is now controllable only through MAXScript.

Interfaces > Core Interfaces > IBitmapPager

Core Interfaces - Quick Navigation

WARNING:
The Bitmap Pager reduces the memory footprint of the renderer in order to improve system stability by minimizing the chances for out-of-memory problems, especially when rendering to a very large output image size (4K and higher). However, the Pager operates by swapping memory to disk, and therefore comes at a cost to performance. If the memory footprint is not a concern, for example on 64 bit OS running a 64 bit build of 3ds Max with large amounts of memory, the pager may be disabled using the following MAXScript call to improve rendering performance: IBitmapPager.enabled = false This value does not take effect until the scene is reloaded! The value can be modified superficially at any time. The value is written to the file upon file save. However, disk paging never becomes enabled or disabled except when a scene is loaded, so changes to the value do not take effect unless the scene is saved and then reloaded!

WARNING:

The Bitmap Pager reduces the memory footprint of the renderer in order to improve system stability by minimizing the chances for out-of-memory problems, especially when rendering to a very large output image size (4K and higher).

However, the Pager operates by swapping memory to disk, and therefore comes at a cost to performance.

If the memory footprint is not a concern, for example on 64 bit OS running a 64 bit build of 3ds Max with large amounts of memory, the pager may be disabled using the following MAXScript call to improve rendering performance:

IBitmapPager.enabled = false

This value does not take effect until the scene is reloaded!

The value can be modified superficially at any time. The value is written to the file upon file save. However, disk paging never becomes enabled or disabled except when a scene is loaded, so changes to the value do not take effect unless the scene is saved and then reloaded!

Properties:

IBitmapPager.enabled : boolean : Read|Write

When set to true the Bitmap Pager is enabled.

When set to false, the Bitmap Pager is disabled.

Defaults to true.

See the above WARNING for more details!

IBitmapPager.pageFilePath : filename : Read|Write

Get/set the Page File Path. Defaults to the Page File path specified by the Customize> Configure System Paths > Page File entry, also returned by getDir #pagefile

IBitmapPager.memoryPadding_percent : float : Read|Write|Validated by Range: 0.0 to 1.0

Get/Set the Memory Padding Percentage as a value in the range from 0.0 to 1.0. This is a percentage (divided by 100) of available memory. Default is 0.2 (20%).

IBitmapPager.memoryLimit_percent : float : Read|Write|Validated by Range: 0.0 to 1.0

Get/Set the Memory Limit Percentage as a value in the range from 0.0 to 1.0. This is a percentage (divided by 100) of the Padded Memory. Default is 0.1.

IBitmapPager.memoryLimitAutoMode : boolean : Read|Write

When set to true, the memory Limit will be calculated automatically using a heuristic method described further on this page. Default is true.

IBitmapPager.memoryLimit_megabytes : integer : Read

Get the Memory Limit in Megabytes.

IBitmapPager.memoryUsedForPager_megabytes : integer : Read

Get the Pager Used Memory in Megabytes.

IBitmapPager.memoryTotalForPager_megabytes : integer : Read

Get the Pager Total Memory in Megabytes.

IBitmapPager.memoryPadding_megabytes : integer : Read

Get the Padding Memory in Megabytes.

IBitmapPager.memoryAvailablePadded_megabytes : integer : Read

Get the Available Padded Memory in Megabytes.

Auto Mode Heuristic - Bitmap Pager:

The amount of usable available memory is computed first. This is the total amount that can be allocated by the pager, minus a padding amount. The padding is 20% by default.
If the system is not rendering, then the limit is set to 50% of usable memory. For example, if 1GB of memory is free, 20% percent is subtracted to yield 800MB, and the pager uses 50%, or 400MB.
If the system is rendering, the pager makes a compromise between its own memory limit, and memory set aside for the renderer. The pager's goal is to have enough memory for all its bitmaps, but not more. The renderer's goal is unknown - there is no method to gauge the renderer's memory needs, so this goal is assumed equal to all usable memory. These two goals are added together, obtaining a goal for the entire system. The pager takes an amount of memory equal to the ratio of its own goal to the total. For example, with 1GB of memory free (800MB considered usable), if the total size of all bitmaps is 400MB, then the pager and renderer goals are 400MB and 800MB respectively, for a system total of 1200MB. The ratio of 400MB to 1200MB is 1/3, so the pager's limit is set to 1/3 of the usable 800MB, or 266MB.
Two adjustments are made.
- First adjustment: During render, if the pager's goal is less than 25% of usable memory, then the pager abandons self-restraint and sets the limit to equal its entire goal. For example, if all bitmaps fit within 18% of usable memory, the prior formula would indicate a limit of 15%, but the pager sets the limit to the full 18%.
- Second adjustment: During render, the pager never sets a limit less than 10%, or more than 50% of usable memory.
Internally, the Auto Mode adjustment happens at the following events: NOTIFY_SYSTEM_STARTUP, NOTIFY_SYSTEM_POST_RESET, NOTIFY_FILE_POST_OPEN, NOTIFY_SYSTEM_POST_NEW, NOTIFY_PRE_RENDER, NOTIFY_POST_RENDER.

Auto Mode Heuristic - mentalray:

Mental ray's limit equals all usable memory not taken by the pager, after the pager's adjustments above. This respects the padding defined by the pager. For example, with 1GB of memory free, then 800MB is considered usable, so mental ray's limit will be 50%-90% of 800MB, or 400MB-720MB, since the pager's limit is always 10%-50% of usable memory.
Internally, the pager's limit is updated during NOTIFY_PRE_RENDER while the mental ray limit is updated later when translating scene options, so the latest pager limit is available.

MAXScript Rendering And Bitmap Pager Improvements

In releases prior to 3ds Max 2011, if a MAXScript performed multiple render() calls, the result of previous renders remained in memory and were not released automatically. The user had to invoke a manual garbage collection to release them. This wasted memory and, because of the Bitmap Pager, disk space.

This issue has been fixed in 3ds Max 2011 by performing periodic garbage collections automatically after rendering.

When rendering through MAXScript, the system now measures any increase in memory usage due to bitmaps. The system sums this value from one render to the next, performing garbage collection whenever the total exceeds a certain threshold. Currently the threshold is the MAXScript Heap Size, defined in the Customize->Preferences dialog, MaxScript tab. Thus a garbage collection is performed following multiple render() calls, where the number of calls required depends on the size of the rendering - larger renders trigger more frequent garbage collection.

Garbage collection will free any memory and disk space allocated by previous render() calls, unless the result of those calls is stored in a variable. For example, calling myImage=render() means the rendered image is held by the variable myImage and will not be collected until a different value is assigned to myImage. For this reason, MAXScript users should be careful to avoid leaving large images assigned to variables, unless an image is needed later. To release an image assigned to a variable, set the variable to undefined, for example by calling myImage=undefined.

It is still possible to run out of disk space. If the disk is full, the new handling does not necessarily perform a garbage collection, so renders may still fail. The new handling only reduces this possibility by placing a low bound on the amount of disk space wasted through MAXScript renders.