The IDLffMJPEG2000::GetSequentialData function method returns the frame index number and retrieves the associated frame data from the frame buffer. The StartSequentialReading method, which loads data into the frame buffer, must be called before calling this method.

The StartSequentialReading, GetSequentialData, ReleaseSequentialData and StopSequentialReading methods are used with a timer mechanism to create a sequential playback.

Note: Always use a widget timer or IDLitWindow timer mechanism to control the playback rate. Avoid using the WAIT procedure with sequential playback methods as the interaction between the procedure and the background processing thread will cause adverse side effects on UNIX platforms.

This method will throw an error if retrieval fails. A CATCH statement can be used to trap these errors.

Syntax

Result = Obj->[IDLffMJPEG2000::]GetSequentialData( Data [, FRAME_NUMBER=variable] [, FRAME_PERIOD=value] [, STEP=value] )

Return Value

If frame data is available in the frame buffer, the method returns a long value indicating the frame buffer index value. This index value is then used by the ReleaseSequentialData call to release the frame.

If no frame data is available, the return index value is -1. This indicates data is being read faster than it is being decompressed.

Arguments

Data

If data is available, the Data variable will contain a two- or three-dimensional array associated with the returned frame index value. This data is essentially a pointer to a slot in the frame buffer, and not a copy of the frame data. Do not attempt to modify this data as it is automatically freed when the ReleaseSequentialData method is called.

The array dimensions depend upon IDLffMJPEG2000::StartSequentialReading method keywords as follows:

Keyword

Result

RGB

RGB is set—array dimensions are [3, width, height].

RGB is not set—array dimensions are [nComponents, width, height] where nComponents, the number of bands or channels of data, depends on the COMPONENT and N_COMPONENTS keyword settings.

If a starting COMPONENT is set, nComponents equals the value specified in N_COMPONENTS unless N_COMPONENTS=1. In this case the array dimensions are [Width, Height].

If a starting COMPONENT is set, but N_COMPONENTS is not set, nComponents equals all available components from the starting component.

If a starting COMPONENT is not set, then nComponents equalsall available components.

REGION

REGION is set—the array width and height are determined by the width and height values in the 4-element REGION vector [startX, startY, width, height].

TILE_INDEX

TILE_INDEX is set—the array width and height values equal the dimensions of a single tile, as defined in the TILE_DIMENSIONS property.

The data type of the result is automatically determined using the BIT_DEPTH and SIGNED properties of the returned components as follows:

Data Properties

Result

BIT_DEPTH ≤ 8 or RGB is set

Byte

BIT_DEPTH ≥9 or ≤16

Integer or unsigned integer

BIT_DEPTH >16

Long or unsigned long

Note: All components in the MJ2 file must have the same bit depth and be either signed or unsigned. Components with different bit depths or a mixture of signed and unsigned data are not supported.

Keywords

FRAME_NUMBER

A variable that will contain the long frame number of the frame that GetSequentialData is currently accessing.

FRAME_PERIOD

A long value specifying the duration of a frame in ticks. Each frame in an MJ2 file can have a unique frame period, which lets you display individual frames for different lengths of time. The FRAME_PERIOD acts in conjunction with the TIMESCALE property to determine the playback rate. See Computing Playback Rate for details.

STEP

A long value indicating the number of frames to skip when retrieving frames from the frame buffer as follows:

Value

Description

0

Reads the next sequential frame (the default)

Positive value

Indicates the number of frames to skip when reading frames in the forward direction

Negative value

Indicates the number of frames to skip when reading frames in the reverse direction

Note: This keyword is intended to be used for manually stepping through frames when sequential playback is paused. This keyword should not be used to skip frames during continuous playback.

If the STEP value results in a frame request that is beyond the range of values defined by IDLffMJPEG2000::StartSequentialReading START_FRAME and STOP_FRAME keywords, the request will wrap to return the appropriate frame.

Examples

The following simple program uses the four sequential playback methods: StartSequentialReading, GetSequentialData, ReleaseSequentialData and StopSequentialReading to display a sample MJ2 animation.

Note: In this example, the playback speed is equal to the frame rate calculated for the first frame. A more sophisticated example would handle varying frame rates. 

;-----------------------------------------------------------------
PRO mj2_simple_sequential_doc_event, sEvent
;
; General widget event where WIDGET_TIMER events are accessed -
; used to control playback rate of frames (vFrameRate).
 
   COMPILE_OPT IDL2, HIDDEN
 
   ; Get the number of frames and the current frame number.
   WIDGET_CONTROL, sEvent.top, GET_UVALUE=pState
 
   ; If the widget had more than one event, the following line
   ; would find timer events.
   IF (TAG_NAMES(sEvent, /STRUCTURE_NAME) EQ 'WIDGET_TIMER') $
      THEN BEGIN
 
      ; Play all available frames (nFrames). Return the frame
      ; period of each frame to compute the playback rate.
      frameIndex = (*pstate).oMJPEG2000->GetSequentialData(Data)
 
      ; If request for data is too fast, handle return of -1.
      IF (frameIndex NE -1) THEN BEGIN
         ; If a frame is available, display RGB data.
         TV, Data, TRUE=1
         ; Release the frame and make buffer slot available.
         (*pState).oMJPEG2000->ReleaseSequentialData, frameIndex
      ENDIF
 
      ; Update timer with frame rate.
      WIDGET_CONTROL, (*pState).wBase, Timer=(*pState).vFrameRate
   ENDIF
END
 
;-----------------------------------------------------------------
;
PRO mj2_timer_doc_cleanup, id
;
; Release the frames from the frame buffer and
; shut down the background processing thread.
; Clean up object and pointer.
 
   WIDGET_CONTROL, id, GET_UVALUE=pState
   Status = (*pState).oMJPEG2000->StopSequentialReading()
   OBJ_DESTROY, (*pState).oMJPEG2000
   PTR_FREE, pState
 
END
 
;-----------------------------------------------------------------
;
PRO mj2_simple_sequential_doc
;
; Create a Motion JPEG2000 object that reads a sample MJ2 file. Use
; a timer mechanism to play back the files at the frame rate of the
; the first frame.
 
   ; Create a Motion JPEG2000 object and read in the
   ; idl_mjpeg2000_example.mj2 sample movie.
   oMJPEG2000 = Obj_New('IDLffMJPEG2000', $
      FILEPATH('idl_mjpeg2000_example.mj2', $
      SUBDIRECTORY=['examples','mjpeg2000']))
 
   ; Get the number of frames and frame dimensions.
   oMJPEG2000->GetProperty, N_FRAMES=nFrames, $
      DIMENSIONS=imageSize, FRAME_PERIOD=vFramePeriod, $
      TIMESCALE=vTimeScale
 
   ; Figure frames per second and print result.
   vFrameRate = FLOAT(vFramePeriod)/vTimeScale
   vFramePerSec =  STRING(1/(vFrameRate))
   PRINT, "Frames per second = " + vFramePerSec
 
   ; Create base and draw widgets.
   wBase = WIDGET_BASE(/COLUMN, $
      TITLE="Simple Sequential Playback", $
      KILL_NOTIFY='mj2_timer_doc_cleanup', UVALUE='TIMER')
   wDraw = WIDGET_DRAW(wBase, XSIZE =imageSize[0], $
      YSIZE=imageSIZE[1])
 
   ; Realize base and initialize timer.
   WIDGET_CONTROL,/REALIZE, wBase
   WIDGET_CONTROL, wBase, TIMER=vFrameRate
 
   ; Start reading the RGB frames into the frame buffer.
   Status = oMJPEG2000->StartSequentialReading(/RGB)
 
   ; Create state structure.
   state = {oMJPEG2000:oMJPEG2000, wBase:wBase, $
      vFrameRate:vFrameRate}
   pState = PTR_NEW(state)
   WIDGET_CONTROL, wBase, set_UVALUE=pstate
 
   XMANAGER, 'mj2_simple_sequential_doc', wBase, /NO_BLOCK
 
END

This example mj2_simple_sequential_doc.pro, is located in the examples/doc/objects subdirectory of the IDL distribution. Run the example procedure by entering mj2_simple_sequential_doc at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT mj2_simple_sequential_doc.pro.

Version History

6.3

Introduced