0
# Drawing & Graphics
1

2
Low-level drawing capabilities for custom graphics including shapes, lines, text rendering, and image display with transformation support. DearPyGui's drawing system provides immediate-mode graphics with GPU acceleration.
3

4
## Capabilities
5

6
### Drawing Containers
7

8
```python { .api }
9
def add_drawlist(*, width: int = '', height: int = '', tag: Union[int, str] = '', parent: Union[int, str] = '', **kwargs) -> Union[int, str]:
10
    """Creates a drawing canvas for custom graphics."""
11

12
def add_viewport_drawlist(*, front: bool = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
13
    """Creates a viewport-level drawing overlay."""
14
```
15

16
### Basic Shape Drawing
17

18
```python { .api }
19
def draw_line(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], *, color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> None:
20
    """Draws a line between two points."""
21

22
def draw_rectangle(pmin: Union[List[float], Tuple[float, ...]], pmax: Union[List[float], Tuple[float, ...]], *, color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', rounding: float = '') -> None:
23
    """Draws a rectangle with optional fill and rounding."""
24

25
def draw_circle(center: Union[List[float], Tuple[float, ...]], radius: float, *, color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', segments: int = '') -> None:
26
    """Draws a circle with optional fill."""
27

28
def draw_ellipse(pmin: Union[List[float], Tuple[float, ...]], pmax: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', segments: int = '') -> Union[int, str]:
29
    """
30
    Draws an ellipse defined by bounding box.
31
    
32
    Parameters:
33
    - pmin, pmax (tuple): Bounding box corners
34
    - color (tuple): Outline color
35
    - fill (tuple): Fill color
36
    - thickness (float): Outline thickness
37
    - segments (int): Number of segments for smoothness
38
    
39
    Returns:
40
    Union[int, str]: Drawing item ID
41
    """
42

43
def draw_triangle(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], p3: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> Union[int, str]:
44
    """
45
    Draws a triangle from three points.
46
    
47
    Parameters:
48
    - p1, p2, p3 (tuple): Triangle vertices
49
    - color (tuple): Outline color
50
    - fill (tuple): Fill color
51
    - thickness (float): Outline thickness
52
    
53
    Returns:
54
    Union[int, str]: Drawing item ID
55
    """
56

57
def draw_quad(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], p3: Union[List[float], Tuple[float, ...]], p4: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> Union[int, str]:
58
    """
59
    Draws a quadrilateral from four points.
60
    
61
    Parameters:
62
    - p1, p2, p3, p4 (tuple): Quad vertices
63
    - color (tuple): Outline color
64
    - fill (tuple): Fill color
65
    - thickness (float): Outline thickness
66
    
67
    Returns:
68
    Union[int, str]: Drawing item ID
69
    """
70

71
def draw_polygon(points: Union[List[Union[List[float], Tuple[float, ...]]], Tuple[Union[List[float], Tuple[float, ...]], ...]], *, color: Union[List[int], Tuple[int, ...]] = '', fill: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> None:
72
    """Draws a polygon from a list of points."""
73

74
def draw_polyline(points: List[List[float]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', closed: bool = '', color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '') -> Union[int, str]:
75
    """
76
    Draws a multi-segment line through points.
77
    
78
    Parameters:
79
    - points (list): List of point coordinates [[x1,y1], [x2,y2], ...]
80
    - closed (bool): Connect last point to first
81
    - color (tuple): Line color
82
    - thickness (float): Line thickness
83
    
84
    Returns:
85
    Union[int, str]: Drawing item ID
86
    """
87

88
def draw_arrow(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', size: int = '') -> Union[int, str]:
89
    """
90
    Draws an arrow from p1 to p2.
91
    
92
    Parameters:
93
    - p1, p2 (tuple): Arrow start and end points
94
    - color (tuple): Arrow color
95
    - thickness (float): Line thickness
96
    - size (int): Arrowhead size
97
    
98
    Returns:
99
    Union[int, str]: Drawing item ID
100
    """
101
```
102

103
### Advanced Curves
104

105
```python { .api }
106
def draw_bezier_cubic(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], p3: Union[List[float], Tuple[float, ...]], p4: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', segments: int = '') -> Union[int, str]:
107
    """
108
    Draws a cubic Bézier curve.
109
    
110
    Parameters:
111
    - p1 (tuple): Start point
112
    - p2, p3 (tuple): Control points
113
    - p4 (tuple): End point
114
    - color (tuple): Line color
115
    - thickness (float): Line thickness
116
    - segments (int): Number of segments for smoothness
117
    
118
    Returns:
119
    Union[int, str]: Drawing item ID
120
    """
121

122
def draw_bezier_quadratic(p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], p3: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', color: Union[List[int], Tuple[int, ...]] = '', thickness: float = '', segments: int = '') -> Union[int, str]:
123
    """
124
    Draws a quadratic Bézier curve.
125
    
126
    Parameters:
127
    - p1 (tuple): Start point
128
    - p2 (tuple): Control point
129
    - p3 (tuple): End point
130
    - color (tuple): Line color
131
    - thickness (float): Line thickness
132
    - segments (int): Number of segments for smoothness
133
    
134
    Returns:
135
    Union[int, str]: Drawing item ID
136
    """
137
```
138

139
### Text and Image Drawing
140

141
```python { .api }
142
def draw_text(pos: Union[List[float], Tuple[float, ...]], text: str, *, color: Union[List[int], Tuple[int, ...]] = '', size: float = '') -> None:
143
    """Draws text at the specified position."""
144

145
def draw_image(texture_tag: Union[int, str], pmin: Union[List[float], Tuple[float, ...]], pmax: Union[List[float], Tuple[float, ...]], *, uv_min: Union[List[float], Tuple[float, ...]] = '', uv_max: Union[List[float], Tuple[float, ...]] = '', color: Union[List[int], Tuple[int, ...]] = '') -> None:
146
    """Draws an image from a texture."""
147

148
def draw_image_quad(texture_tag: Union[int, str], p1: Union[List[float], Tuple[float, ...]], p2: Union[List[float], Tuple[float, ...]], p3: Union[List[float], Tuple[float, ...]], p4: Union[List[float], Tuple[float, ...]], *, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', uv1: Union[List[float], Tuple[float, ...]] = '', uv2: Union[List[float], Tuple[float, ...]] = '', uv3: Union[List[float], Tuple[float, ...]] = '', uv4: Union[List[float], Tuple[float, ...]] = '', color: Union[List[int], Tuple[int, ...]] = '') -> Union[int, str]:
149
    """
150
    Draws an image mapped to a quadrilateral.
151
    
152
    Parameters:
153
    - texture_tag: Texture to use
154
    - p1, p2, p3, p4 (tuple): Quad vertices
155
    - uv1, uv2, uv3, uv4 (tuple): UV coordinates for each vertex
156
    - color (tuple): Tint color
157
    
158
    Returns:
159
    Union[int, str]: Drawing item ID
160
    """
161
```
162

163
### Transformation Matrices
164

165
```python { .api }
166
def apply_transform(item: Union[int, str], transform: Any) -> None:
167
    """Applies a transformation matrix to drawing operations."""
168

169
def create_translation_matrix(translation: Union[List[float], Tuple[float, ...]]) -> Any:
170
    """
171
    Creates a translation transformation matrix.
172
    
173
    Parameters:
174
    - translation (tuple): Translation vector [x, y] or [x, y, z]
175
    
176
    Returns:
177
    Any: Transformation matrix
178
    """
179

180
def create_rotation_matrix(angle: float, axis: Union[List[float], Tuple[float, ...]] = '') -> Any:
181
    """
182
    Creates a rotation transformation matrix.
183
    
184
    Parameters:
185
    - angle (float): Rotation angle in radians
186
    - axis (tuple): Rotation axis for 3D rotations [x, y, z]
187
    
188
    Returns:
189
    Any: Transformation matrix
190
    """
191

192
def create_scale_matrix(scales: Union[List[float], Tuple[float, ...]]) -> Any:
193
    """
194
    Creates a scale transformation matrix.
195
    
196
    Parameters:
197
    - scales (tuple): Scale factors [x, y] or [x, y, z]
198
    
199
    Returns:
200
    Any: Transformation matrix
201
    """
202

203
def create_perspective_matrix(fov: float, aspect: float, zNear: float, zFar: float) -> Any:
204
    """
205
    Creates a perspective projection matrix.
206
    
207
    Parameters:
208
    - fov (float): Field of view angle in radians
209
    - aspect (float): Aspect ratio (width/height)
210
    - zNear (float): Near clipping plane distance
211
    - zFar (float): Far clipping plane distance
212
    
213
    Returns:
214
    Any: Perspective projection matrix
215
    """
216

217
def create_orthographic_matrix(left: float, right: float, bottom: float, top: float, zNear: float, zFar: float) -> Any:
218
    """
219
    Creates an orthographic projection matrix.
220
    
221
    Parameters:
222
    - left, right (float): Left and right clipping planes
223
    - bottom, top (float): Bottom and top clipping planes  
224
    - zNear, zFar (float): Near and far clipping planes
225
    
226
    Returns:
227
    Any: Orthographic projection matrix
228
    """
229

230
def create_lookat_matrix(eye: Union[List[float], Tuple[float, ...]], target: Union[List[float], Tuple[float, ...]], up: Union[List[float], Tuple[float, ...]]) -> Any:
231
    """
232
    Creates a look-at view matrix.
233
    
234
    Parameters:
235
    - eye (tuple): Camera position [x, y, z]
236
    - target (tuple): Target position [x, y, z]
237
    - up (tuple): Up vector [x, y, z]
238
    
239
    Returns:
240
    Any: Look-at view matrix
241
    """
242

243
def create_fps_matrix(eye: Union[List[float], Tuple[float, ...]], pitch: float, yaw: float) -> Any:
244
    """
245
    Creates a first-person-shooter style view matrix.
246
    
247
    Parameters:
248
    - eye (tuple): Camera position [x, y, z]
249
    - pitch (float): Pitch angle in radians
250
    - yaw (float): Yaw angle in radians
251
    
252
    Returns:
253
    Any: FPS view matrix
254
    """
255
```
256

257
## Usage Example
258

259
```python
260
import dearpygui.dearpygui as dpg
261
import math
262

263
with dpg.window(label="Drawing Example", width=600, height=500):
264
    with dpg.drawlist(width=500, height=400):
265
        # Draw shapes
266
        dpg.draw_rectangle([50, 50], [150, 100], color=[255, 0, 0], fill=[255, 0, 0, 100])
267
        dpg.draw_circle([250, 150], 50, color=[0, 255, 0], thickness=3)
268
        dpg.draw_line([300, 50], [400, 150], color=[0, 0, 255], thickness=2)
269
        dpg.draw_text([50, 200], "Hello Graphics!", color=[255, 255, 255], size=20)
270
```