Clipping And Scrolling (frames)
OSL provides a powerful frame system for clipping content and creating scrollable areas in your applications.
Basic Clipping
The frame
command lets you define a rectangular area that clips (masks) any content drawn inside it. Content outside the frame's boundaries will not be visible.
Syntax
frame left top right bottom (
// Content to be clipped goes here
)
The frame boundaries are defined by four coordinates:
left
: Left edge position (x-coordinate)top
: Top edge position (y-coordinate)right
: Right edge position (x-coordinate)bottom
: Bottom edge position (y-coordinate)
Example: Basic Clipping
// Define frame boundaries
left = -100
right = 100 // Creates a 200px wide frame
top = 100
bottom = -100 // Creates a 200px tall frame
mainloop:
frame left top right bottom (
// Draw a large square that will be clipped
square 10000 10000 20
// Only the portion within the 200x200 frame will be visible
)
Scrollable Frames
You can create scrollable areas in two ways:
Two-dimensional scrolling with content width and height
Vertical-only scrolling with just content height
Two-Dimensional Scrolling Syntax
frame left top right bottom [content_width, content_height] "frame_id" (
// Scrollable content goes here
)
Additional parameters:
[content_width, content_height]
: Dimensions of the scrollable content area"frame_id"
: Unique identifier for the scrollable frame
Vertical-Only Scrolling Syntax
frame left top right bottom content_height "frame_id" (
// Vertically scrollable content goes here
)
Additional parameters:
content_height
: Total height of the scrollable content (integer)"frame_id"
: Unique identifier for the scrollable frame
Example: Two-Dimensional Scrolling
// Style settings
text_size = 10
image_width = 150
mainloop:
// Create a 200x200 frame with 1000x200 scrollable content
frame -100 100 100 -100 [1000, 200] "my_scroll_frame" (
// Position content using scroll coordinates
goto scroll_x scroll_y
// Add content that can scroll both horizontally and vertically
text "Header Text" text_size
change_y -20
image my_image image_width
)
Example: Vertical-Only Scrolling
mainloop:
// Create a 200x200 frame with 500px scrollable height
frame -100 100 100 -100 500 "vertical_scroll" (
// Position content using scroll_y only
goto 0 scroll_y
// Add vertically scrolling content
text "Title" text_size
change_y -30
text "Long content that scrolls vertically..." text_size
change_y -20
image my_image image_width
)
Important Notes
Frame Coordinates
Coordinates are relative to the center of the screen
Positive Y goes up, negative Y goes down
Frame size = (right - left) × (top - bottom)
Scrolling Behavior
Scrollbars appear automatically when content exceeds frame size
Scroll position is tracked via
scroll_x
andscroll_y
variables orframe.scroll
frame.scroll_h
respectivelyContent coordinates are relative to scroll position
Best Practices
Use meaningful frame IDs for easier management
Consider padding inside frames for better appearance
Update content layout based on scroll position
Clean up or reset scroll position when needed
Common Use Cases
Long text documents
Image galleries
Lists and menus
Content that exceeds screen size
Last updated
Was this helpful?