Click or drag to resize

IMcImageSetNextAccessPriority Method

Sets the next access priority for specified frames

Namespace:  MediaCy.IQL.Engine
Assembly:  MediaCy.IQL.Engine (in MediaCy.IQL.Engine.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Sub SetNextAccessPriority ( 
	Optional BasePriority As Double = 110,
	<OptionalAttribute> FramesSelector As Object,
	Optional DeltaEndPriority As Double = -5
)

Parameters

BasePriority (Optional)
Type: SystemDouble
The McFrame.NextAccessPriority value to be given to the first frame in the sequence of given by the FramesSelector argument. This value is 110.0 by default, which is higher than the default NextAccessPriority given to any frame after it is accessed.
FramesSelector (Optional)
Type: SystemObject
An optional selector for the frames to be set. If missing or Empty then if UseActiveFrameRange is True, the frames are those in the ActiveFrameRange and if UseActiveFrameRange is False, only the ActiveFrame is set. If the argument is given, then if it is a scalar -1, all frames in the image are set in order from first to last. The selector may be an array of VARIANT, in which case the contents of each VARIANT are added to the list of frames. Each VARIANT may be a single scalar index value (if negative, then all frames are added), or it may be a single scalar LONGRANGE giving Start and End frame indices, or it may be an array of index values or an array of LONGRANGE index ranges. In addition, it may be a McFrame object instance or an array of them; each of these McFrame instances must one of the frames in this McImage's frame list (see the Frame property). Finally, the FramesSelector argument may be a McFrames collection (or an array of them) with a ParentImage the same as this one. In this case the entire contents of the McFrames collection(s) is added the list of frames to set.
DeltaEndPriority (Optional)
Type: SystemDouble
The offset from the BasePriority that is the the McFrame.NextAccessPriority value to be given to the last frame in the sequence of given by the FramesSelector argument. This value is -5.0 by default, so that for the default BasePriority value of 110, the last frame is given a priority of 105. Note that if you are planning to traverse the frames in reverse order (as in playing a sequence backwards), then the appropriate value for DeltaEndPriority will usually be a positve value (e.g., +5).
Remarks
McFrame.NextAccessPriority is the measure used to determine which frames are likely to be needed again soon. This information helps choose the memory to be spooled out to disk when image memory usage approaches the allowed limits. When operations are being performed on multiple frames of a multi-frame image, you will want to keep frames likely to be needed next in memory to the extent possible. When UseActiveFrameRange is True, most image operations will loop through the frames in the ActiveFrameRange, performing the operation on each frame in turn. Thus before performing the operation, you want all ActiveFrameRange frames to have a priority higher than the default of 100 (given whenever a frame was last accessed), and you want frames earlier in the sequence to have a higher priority than frames later in the sequence. After each frame is operated on, then the NextAccessPriority for that frame can be set to a lower value (See example). The default parameters for this method support the above scenario by assigning a NextAccessPriority of 110 to the first frame in the ActiveFrameRange (or to the ActiveFrame if UserActiveFrameRange is False) and then successively lower priorities to other frames until the last frame is given a NextAccessPriority of 105. It is the callers responsibility to set the NextAccessPriority after it has been operated on. Frames sharing the same memory node all share the same NextAccessPriority (which is whatever was assigned last). The NextAccessPriority decays linearly over about 10 minutes from its assigned value to one ten thousanth of that, so that frames not accessed recently will have steadily lower priority.
Examples
VB
Copy
'Create a multiframe image and set every other frame to white
Private Function MakeBigSequence(nFrames As Long) As McImage
    Dim typeBS As McImageType
    Set typeBS = New McImageType
    typeBS.Initialize mcoFlatArray, mcpdtInteger, mciMonochrome, mcbpc8Bits, 1
'    typeBS.Initialize mcoDIBArray, mcpdtInteger, mciMonochrome, mcbpc8Bits, 1
        'note: typeBS is the same as mciqtGray (i.e., 8-bit monochrome)
    Dim imgBS As McImage
    Set imgBS = Images.Add("BigSeq", 1024, 1024, nFrames, typeBS)
'    Set imgBS = Images.Add("BigSeq", 1024, 1024, nFrames, typeBS, mcicfContiguous)
    Set typeBS = Nothing
'        'set even numbered frames to white
    imgBS.ActiveFrameRange = McOpMul(McOpFillIn(0&, nFrames / 2), 2) '0 to nFrames-2 step 2
    imgBS.UseActiveFrameRange = True
    imgBS.Clear , 255
    Set MakeBigSequence = imgBS
        'NOTE: on exit the ActiveFrameRange is left set to even numbered frames
End Function 'MakeBigSequence

'Set the AOI of frames in the active frame range to ascending gray levels
Private Sub SetSequenceToAscendingGray(img As McImage)
        'set ActiveFrameRange frames NextAccessPriorty from 110 down to 105
    img.SetNextAccessPriority 110, img.ActiveFrameRange, -5
    img.SetNextAccessPriority 'same as above using defaults

        'Get the ActiveFrameRange as a McFrames collection
    Dim framesActiveRange As McFrames
    Set framesActiveRange = img.Frames(img.ActiveFrameRange)

        'Show a progress meter
    Dim bs As McBusyState
    Set bs = SetBusyState
    bs.SetProgressInfo "Ascending gray", mcpacTopLevelCancelOnly, 0, framesActiveRange.Count

        'loop frames, setting the AOI of each to an ascending gray value
    Dim dGryStep As Double, dGry As Double, lFrame As Long
    dGryStep = (img.RangeMax - img.RangeMin) / framesActiveRange.Count
    dGry = img.RangeMin
    img.BeginEndUpdateBlock True 'begin update block
    For lFrame = 0 To framesActiveRange.Count - 1
        If bs.SetProgress(lFrame) Then Exit For 'allow user to cancel operation
        Dim raT As McRegionAccess
        Set raT = img.Aoi.AccessMaskedImageData(, , framesActiveRange(lFrame).FrameIndex)
        raT.SetToConstant dGry
            'we are done with this frame, release raT 1st, so
        Set raT = Nothing 'it does not try to set NextAccessPriority
            'we likely won't need this frame again soon, so set it to
        framesActiveRange(lFrame).NextAccessPriority = 100 'the default priority
        dGry = dGry + dGryStep 'for next loop
    Next 'lFrame
    img.BeginEndUpdateBlock False 'end update block
End Sub 'SetSequenceToAscendingGray

Sub RunATest()
    'Note: NextAccessPriority is all about controlling swapping to disk,
    'so we need to create an image that is big enough to cause swapping.
    'Each frame created by MakeBigSequence is a Megabyte, so 1024 frames is 1 GB.
    'With the memory management defaults, swapping starts when 80% of physical
    'memory is used.  In the test below, 128 frames are created, but the
    'MemoryUsageLimit is set to 5 percent, so swapping occurs much more frequently
    'than it would with the default of 80 percent.
    '
    Dim nReplyToMsgBox As Integer
    nReplyToMsgBox = MsgBox("WARNING: This example is designed to test disk swapping and so takes a long time." + vbCrLf + _
        "You can press Esc at any time to end it, but unless you want to test swapping don't run it." + vbCrLf + _
        "Continue with the test?", vbDefaultButton2 + vbYesNo)
    If nReplyToMsgBox = vbNo Then Exit Sub
    'ELSE go for it.
    RestoreMemoryManagerDefaults  'Set Memory swapping parameters to defaults

    Dim nFrames As Long
 '   nFrames = 1024
    nFrames = 128
    Dim imgMBS As McImage
    Set imgMBS = MakeBigSequence(nFrames) 'leaves ActiveFrameRange at even frames only
        'Make memory swapping parameters tighter, so swapping will happen earlier
    Images.MemoryVirtualReserve = 50 'lots of reserve
    Images.MemoryUsageLimit = 5 'small percentage, so swap a lot

        'Create an elliptical AOI
    imgMBS.Aoi.SetEllipse -1, 250, 250, 200, 150
        'Set the AOI of the ActiveFrameRange frames to increasing Gray
    SetSequenceToAscendingGray imgMBS
    imgMBS.ActiveFrameRange = -1 'Set ActiveFrameRange to display all frames
    ActiveWindow.View.SequencePlayForward 'and play the sequence
End Sub 'RunATest

Sub RestoreMemoryManagerDefaults()
    Images.MemoryVirtualReserve = 10
    Images.MemoryUsageLimit = 80
End Sub 'RestoreMemoryManagerDefaults
See Also