Memory Elements

This topic explains how memory operators in a VisualApplets design map to physical memory on the target hardware, and when you use which type. After you have read this topic, you understand the difference between FPGA-internal memory (for example block RAM) and frame grabber DRAM, how FIFO-style buffers differ from random-access frame buffers, how shared DRAM bandwidth limits designs with several RAM operators, and how you recognize memory-related problems in simulation and on hardware.

Key Terms

Memory operators in a VisualApplets design use one of two physical memory locations on the target hardware: inside the FPGA on the frame grabber (small, fast, local) and on the frame grabber outside the FPGA (DRAM — more capacity for line and frame buffers).

FillLevel tells you how full a buffer is (in percent) at runtime on the hardware, for example in microDisplay X. A buffer that stays near 100% often points to a bottleneck or deadlock. As a starting point, place a buffer after the camera.

For platform RAM sizes, data widths, and bandwidth values, see Device Resources.

FPGA Memory vs. Frame Grabber DRAM

VisualApplets memory operators fall into two groups by where they store data on the frame grabber. A second distinction is how they access that data: FIFO-style buffers versus random-access or multi-ROI frame buffers. The Overview of the Memory Library in the Operator Reference shows where each memory operator stores its data. The RAM resource in VisualApplets is a device-resource token that maps to board DRAM. It is not memory inside the VisualApplets application.

Property	FPGA-internal memory	Frame grabber DRAM
Typical operators	ImageFifo; for small random-access cases also FrameMemoryRandomRd / LineMemoryRandomRd	ImageBuffer, LineBuffer, FrameBufferRandomRead, FrameBufferMultiRoi, FrameBufferMultiRoiDyn
Location	Inside the FPGA (BRAM, LUT RAM, or URAM on imaFlex CXP-12 Quad/Penta)	On the board, outside the FPGA
Capacity	Limited; full-resolution frames often exceed available FPGA memory	Higher; suitable for many lines or full frames
レイテンシー	Low; no access to an external DRAM bus	Line-oriented FIFOs add at least one line
VisualApplets RAM resource	No — does not reserve a RAM device resource	Yes — one RAM resource per instance, mapped to board DRAM
Bandwidth	Local; operators don't compete for the frame grabber RAM interface	Shared among RAM operators on the same physical interface — see Sharing DRAM Bandwidth

Use the table in Choosing a Memory Operator to pick an operator, then read the matching operator section for parameters and platform details.

Choosing a Memory Operator

使用事例	Prefer
Small buffer, low latency, no DRAM bandwidth cost	ImageFifo (FPGA-internal)
Image FIFO on mE5, peak absorption, ROI	ImageBuffer (DRAM)
Line FIFO on imaFlex CXP-12 Quad/Penta	LineBuffer (DRAM)
Buffer before SYNC with small delay	ImageFifo (or larger DRAM buffer if delay is large)
Full-frame store with random pixel read	FrameBufferRandomRead (DRAM)
Multiple or dynamic ROIs from one buffer	FrameBufferMultiRoi / FrameBufferMultiRoiDyn (DRAM)

Design Guideline

Basler recommends that you use at least one DRAM operator in a design to compensate for data bursts from the camera. That DRAM buffer is the default camera decoupling path (LineBuffer または ImageBuffer). ImageFifo is not a substitute for that DRAM buffer when you need to absorb camera bursts.

ImageFifo

イメージ ImageFifo operator queues image data as a first-in, first-out buffer in FPGA-internal memory. You size the buffer with the EntitiesToStore and EntityType parameters. EntityType has the values PIXEL, LINE, or FRAME. Data is forwarded immediately when the output is free. The buffer fills when downstream modules block.

パラメーターを InfiniteSource parameter of the ImageFifo operator to ENABLED when the input comes from a non-stoppable source such as a camera.

情報

イメージ ImageFifo operator buffers only a relatively small number of pixels. Therefore, there is a significant risk of a FIFO overflow, which isn't always handled internally in a robust way by the operator. For non-stoppable streams, Basler recommends combining ImageFifo with a preceding Overflow operator, or using the ImageFlowControl operator instead of the ImageFifo operator. The ImageFlowControl operator combines FIFO buffering with integrated overflow handling.

With the parameter ImplementationType you can select AUTO (default), BRAM, LUTRAM, or — on imaFlex CXP-12 Quad/Penta — URAM. Basler recommends to always use AUTO unless a specific FPGA resource type runs short.

For details about the operator, see ImageFifo in the Operator Reference.

ImageBuffer and LineBuffer

イメージ ImageBuffer (microEnable 5) and the LineBuffer (imaFlex) operators work like a line-oriented FIFO: Completed lines in the selected ROI are forwarded as soon as downstream modules can accept them. Latency is at least one line. Latency grows if the buffer fills because the output is blocked. See also レイテンシー Tutorial topic.

Platform Note: ImageBuffer vs. LineBuffer

Operator	Platforms
ImageBuffer	microEnable 5 (mE5)
LineBuffer	imaFlex CXP-12 Quad / Penta

imaFlex CXP-12 Quad and Penta don't support the ImageBuffer operator. When you convert a design from mE5 to imaFlex, VisualApplets replaces each ImageBuffer operator with a LineBuffer operator. The LineBuffer operator provides the same core buffering and ROI features for the imaFlex platforms.

Defining Regions of Interest (ROI) with ImageBuffer and LineBuffer

With the ImageBuffer and LineBuffer operators, you can also define regions of interest (ROIs). You do that by setting the XOffset, XLength, YOffset, and YLength parameters. Edge cases are documented in the Operator Reference: For example, if the input is smaller than the requested ROI, or if your design is in Line1D mode, or if you have undefined content for extra pixels.

For details about the operator, see LineBuffer in the Operator Reference and ImageBuffer in the Operator Reference.

Monitoring Buffer Usage and Overflow

イメージ ImageBuffer and LineBuffer operators provide the following status parameters to monitor buffer usage and overflow:

パラメーター	意味
FillLevel	Defines how full the buffer RAM is, in percent (on ImageBuffer in 25% steps).
LineCount	Indicates the current number of lines stored. Only available for the LineBuffer operator.
Overflow	Indicates that the buffer can't accept more data without exceeding capacity. This status parameter is not the same as the Overflow operator in the Synchronization library, and not the same as arithmetic overflow. See Stoppable and Non-Stoppable Data Streams Tutorial topic and Bit Arithmetic Tutorial topic.

If an overflow occurs, incoming data may be discarded and the effective image height might be reduced. Incomplete images can remain in the memory until the operator recovers. Overflow applies when the source is non-stoppable and InfiniteSource is ENABLED. Set InfiniteSource to ENABLED when the buffer sits directly after a camera or another infinite source. See also Stoppable and Non-Stoppable Data Streams Tutorial topic. For how to use these parameters when debugging, see Recognizing Memory-Related Errors.

On the LineBuffer operator, Basler recommends enabling the WritePriority parameter when InfiniteSource is ENABLED. If WritePriority is ENABLED, write bursts from the camera are preferred over reads while the temporary write rate exceeds available DRAM bandwidth. The average bandwidth must still stay within the share available to that operator.

イメージ LineBuffer operator can also convert parallelism between input and output with the module parameter ParallelismConverter, so you don't always need a separate PARALLELup / PARALLELdn. See also Parallelism Tutorial topic.

Full Frames, Random Access, Multi-ROI with the FrameBuffer Operators

イメージ FrameBufferRandomRead, FrameBufferMultiRoi, and FrameBufferMultiRoiDyn operators store full images or large regions and read them in an order that is not a strict line FIFO. Use them when you need random pixel access or multiple ROIs from one buffer.

FrameBufferRandomRead

FrameBufferRandomRead writes the input image into DRAM, then reads pixels by column and row addresses on dedicated address ports. Use it for geometric transforms, remapping, and other random-access patterns.

For small frames or lines, prefer FPGA-internal operators such as FrameMemoryRandomRd または LineMemoryRandomRd instead of DRAM operators.

For details about the operator, see FrameBufferRandomRead in the Operator Reference.

FrameBufferMultiRoi and FrameBufferMultiRoiDyn

イメージ FrameBufferMultiRoi and FrameBufferMultiRoiDyn operators store image data and output multiple regions of interest. FrameBufferMultiRoiDyn allows dynamic ROI size and position from control links.

Sharing DRAM Bandwidth

Each DRAM operator needs one VisualApplets resource of type RAM. That resource is a slot in the VisualApplets resource model. It maps to physical DRAM on the frame grabber. On imaFlex and microEnable 5 marathon platforms, all operators that reserve a RAM resource share the physical DRAM. Each operator gets a dedicated, non-overlapping memory region, but size and bandwidth are divided among active RAM operators on the same physical interface.

Consequences:

• Every read and every write consumes bandwidth on the shared interface.
• With several DRAM instances or high throughput, the total traffic can exceed the platform limit.
• Excess demand leads to blocking, rising FillLevel, overflow, or a lower sustainable frame rate.

Look up RAM size, RAM data width, and RAM bandwidth total (shared) for your platform in Device Resources.

Allocate resources in the Resources dialog when needed; see Allocation of Device Resources in Device Resources.

Bandwidth Calculation Notes

The Shared Memory Application Note explains how to use RAM size and RAM data width efficiently.

Key points:

1. Read and write share the interface. For a single DRAM operator, divide the platform maximum bandwidth by 2 when you estimate the usable image data rate (half for writing, half for reading), then apply efficiency factors. Documented bandwidth values are theoretical maxima; real efficiency is lower.

2. Use as much of the RAM data width as practical. The link's effective RAM data width is:

bit width × parallelism × kernel elements

That product is the effective width of each DRAM access. Do not confuse it with the pixel-rate bandwidth from parallelism × Base Design Clock. Maximum DRAM throughput is reached when the product matches the platform RAM data width without exceeding it, for example 256 bit, 384 bit, or 640 bit, depending on the board. Matching the product to the maximum RAM data width uses the full write and read bandwidth of the DRAM; if the value is much lower, DRAM access can become a bottleneck. A design with 8 bit × parallelism 4 uses only 32 bit of a 256-bit interface and wastes bandwidth headroom.

1. Multiple DRAM operators share bandwidth. On shared-memory platforms, the bandwidth available to one operator scales roughly with 1 / (number of RAM operators) on that interface. Details differ by platform as documented in Device Resources and the Application Note: Shared Memory (see Related Topics).

2. Balance operators across independent RAM banks when the platform provides more than one physical interface, for example as the imaFlex 2 Dual 100 does. Bandwidth is shared only among operators on the same physical bank.

Design Guideline

Plan RAM usage early. Every additional DRAM operator reduces the bandwidth available to the others on the same physical memory interface. Before you add another DRAM buffer, calculate the combined read/write traffic and compare it with the shared bandwidth available for your platform (see Device Resources). Prefer ImageFifo (FPGA memory) for small decoupling tasks so you don't spend DRAM bandwidth unnecessarily.

Recognizing Memory-Related Errors

VisualApplets can't always validate that a design has enough memory of the right type and size for every runtime scenario. You must choose operators and buffer sizes that match your image dimensions, rates, and synchronization needs.

Simulation may run successfully even when buffers are undersized for hardware. Failures often appear only on the frame grabber: for example, no image is output in the SDK although simulation looked fine.

Common causes are SYNC deadlocks and insufficient or wrong memory.

To avoid these issues, do these checks:

• Run Design Rules Check Level 1 and Level 2 after wiring buffers and DMA paths.
• On hardware, watch FillLevel (and Overflow where available), for example in microDisplay X. Persistent 100% fill often indicates a deadlock or a bandwidth bottleneck.
• With several DRAM operators, open Design → Device Resources and verify RAM allocation and expected bandwidth share.
• For infinite sources, confirm that InfiniteSource is ENABLED on every buffer that accepts a non-stoppable stream.

Typical Pipeline Examples

Camera to DMA Through a DRAM Line Buffer

The smallest possible design has one camera operator, one DRAM buffer with InfiniteSource set to ENABLED, and one DmaToPC operator:

Use this buffer to absorb peaks and to feed line-based processing. Watch FillLevel on hardware; a value that stays near 100% often indicates a bottleneck or deadlock. See Recognizing Memory-Related Errors.

Camera Through LineBuffer into a 3×3 Kernel

In the following design, the DRAM buffer supplies lines for a neighborhood operator that builds a kernel (for example 3×3). The buffer adds at least one line of latency — more if it fills because the filter path blocks. Account for the shared DRAM bandwidth of the LineBuffer operator as well. The Design Rules Check in the screenshot confirms that the link formats and buffer settings are consistent before you build.

関連トピック

• Stoppable and Non-Stoppable Data Streams Tutorial topic — InfiniteSource, overflow, camera decoupling
• Parallelism Tutorial topic — bandwidth, RAM data width, LineBuffer parallelism conversion
• Latency Tutorial topic — line latency of buffer operators
• Operator Types and Synchronization Tutorial topic — buffers before SYNC
• Device Resources — platform RAM and Shared Memory Concept
• Shared Memory Application Note — efficient DRAM usage and bandwidth examples
• Memory Library in the Operator Reference — operator overview by memory type