-
Notifications
You must be signed in to change notification settings - Fork 0
Draw Stimuli Package
This is the documentation page for the Draw Stimuli Package. For information on installing and using a package in your experiment, see this guide
Current Version: v1.0
The Draw Stimuli Package contains functions for drawing things to the on screen canvas. It has functions for handling drawing to the onscreen canvas in a safe and easy way.
Void DrawStimuli_DrawImage( Integer source_x, Integer source_y, Integer dest_x, Integer dest_y, String file, [Double Scale, String transparent_color )
This function draws an image to the canvas.
It takes an image specified by file, then draws that to an offscreen canvas
That image is then copied over to the drawing canvas
Use DrawStimuli_ShowCanvas() to display the drawing canvas on the on screen display
The image canvas is transparent, so if you set a source color key on that canvas to the color of your image you wish to be transparent
then the image will be drawn with that color transparent
Void DrawStimuli_DrawText( String text_str, Integer text_x, Integer text_y )
This function draws a blurb of text to the screen. The text to draw is the argument text_str. The text is drawn such that the center of the text will lie on the point (text_x, text_y).
Void DrawStimuli_DrawMask( Integer mask_x, Integer mask_y, Double mask_width, Double mask_height, Integer num_rows, Integer num_columns )
This function draws a multi-colored grid of rectangles centered on the point (mask_x, mask_y) with height mask_height and width mask_width. The num_rows and num_columns determine how many rows and columns of rectangles are rendered in the mask image. The colors are randomly picked from a set list of 18 colors.
Void DrawStimuli_ShowCanvas()
This function displays the off screen drawing canvas onto the on screen display at the next vertical refresh. It takes no arguments. Use this to display what has been created on the drawing canvas by another function, such as Void DrawStimuli_DrawImage().
Canvas DrawStimuli_GetCanvas( Integer canvas_num)
This function is used to get a reference to one of the canvases that belong to the Draw Stimuli Package. Its only argument is the Integer canvas_num. The number you pass in will determine which canvas is returned by this function. This is very useful for when you need to set the properties of a canvas within the package. The canvases are indexed by number according to the following:
- On screen canvas
- Off screen drawing canvas
- Off screen image canvas
Use the function as shown here:
Dim drawing_canvas as Canvas
Set drawing_canvas = DrawStimuli_GetCanvas(1)
Void DrawStimuli_CloneCanvas()
This function copies the contents of the on screen canvas onto the drawing canvas. This is a useful function for when you have something displayed on the screen and you want to draw something on top of it. Call this function to copy over the screen, and then call a function to draw something. When you call DrawStimuli_ShowCanvas() it will contain the previously copied screen with the new drawing on top of it.
Void DrawStimuli_GetPosition( Integer position_index, Point [ByRef] return_point )
This function will allow you to retrieve a position that has been generated by one of the following generate positions functions. The function takes in an index (starting from zero) of the position you wish to retireve, and then stores the position in the return_point. If you generated 5 positions, then you will need to call this function 5 times in order to retrieve all 5 points (this is because E-Prime packages cannot accept or return arrays...). The easiest way to do this is with a loop like so:
Dim num_positions as Integer
num_positions = 5
Dim min_distance as Double
min_distance = 10.0
Dim bounding_box as Rect
bounding_box.Left = 0
bounding_box.Right = Display.Xres
bounding_box.Top = 0
bounding_box.Bottom = Display.Yres
Dim positions( 0 to num_positions ) as Point
Call DrawStimuli_GenerateBoundedPositions( bounding_box, num_positions, min_distance, "none" )
Dim i as Integer
For i = 0 to num_positions - 1
Call DrawStimuli_GetPosition( i, positions(i) )
Next i
Void DrawStimuli_GenerateBoundedPositions( Rect bounding_box, Integer num_positions, Double min_distance [, String scale_factor ])
This function generates a list of random positions that fall within bounding_box. Num_positions determines the number of positions that will be generated. Min_distance determines the minimum distance that must exits between any two given points. Due to the constraints of generating positions within a limited frame and with some distance of separation, the algorithm will take a long time to finish for large values of min_distance and small bounding_boxes. If you wish to get extra performance, you can optionally specify a scale_factor. When "none" is given, the algorithm will always use the same bounding_box and min_distance. You can give the value of "min_distance" or "bounding_box" as the scaling factor to allow the function to decrement min_distance or increment bounding_box by one on any failure to generate a correct position. This will speed the function up to some degree, but keep in mind that even with a scale factor, very large min_distances or num_positions, and/or very small bounding_boxes will cause performance issues. See DrawStimuli_GetPosition for retrieval of the generated positions.
Void DrawStimuli_GenerateRadialPositions( Point circle_center, Double circle_radius, Integer num_positions, String distribution [, Double min_distance, Double offset_angle ])
This function generates a list of positions which lie along the circumference of a given circle specified by circle_center and circle_radius. Num_positions determines the number of positions that will be generated. The distribution can either be "uniform" or "random". Uniform distribution will give evenly spaced positions, while random will give randomly spaced positions with an optional min_distance between the points. The optional offset_angle allows you to offset the starting position that is generated (mostly useful for the uniform distribution). See DrawStimuli_GetPosition for retrieval of the generated positions.
Integer DrawStimuli_VisualAngleToPixels( Double visual_angle, Integer distance, Integer screen_width )
This function converts a visual angle to a pixel value. This is useful when trying to draw stimuli according to a given visual angle size. This function is also useful for scaling stimuli with display size. The distance argument is the distance in cm of the subject to the screen. Screen width should also be given in cm.
Double DrawStimuli_GetDistance( Point source, Point destination )
This function returns the distance between two points.
Double DrawStimuli_GetAngleBetweenPoints( Point p1, Point p2 )
This function returns the angle between two points.
Void DrawStimuli_AngleToCoordinate( Double radius, Double angle, Point center, [ByRef] Point return_point )
This function takes in the center point radius of a circle, as well as an angle in relation to the center of the circle. The value of return_point is modified to have the XY coordinates of the point which intersects the given circle at the given angle. Keep in mind the function returns Void, but it modifies the ByReference pointer of return_point.
Integer DrawStimuli_CircleIntersect( Point center1, Double radius1, Point center2, Double radius2, Point [ByRef] return_point1, Point [ByRef] return_point2 )
This function takes in the centers and radii of two circles. It then determines the intersection(s) of these circles. There will either be 0, 1, or 2 intersections, which will be the return value of the function. The intersections, if any, are stored in the ByReference pointers of return_point1 and return_point2.
Double DrawStimuli_Atn2( Double x, Double y )
This is an implementation of the ArcTangent2 function commonly used in geometry and other programming languages.